\documentclass[11pt]{book}

%\RequirePackage[12tabu, orthodox]{nag}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                                                                                                 %
% The mathematical style of these documents follows                                               %
%                                                                                                 %
% A. Thompson and B.N. Taylor. The NIST Guide for the Use of the International System of Units.   %
%    NIST Special Publication 881, 2008.                                                          %
%                                                                                                 %
% http://www.nist.gov/pml/pubs/sp811/index.cfm                                                    %
%                                                                                                 %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\input{../Bibliography/commoncommands}
\IfFileExists{../Bibliography/gitrevision.tex}
{\input{../Bibliography/gitrevision}}
{\newcommand{\gitrevision}{unknown} }


\begin{document}

\bibliographystyle{unsrt}
\pagestyle{empty}


\begin{minipage}[t][9in][s]{6.25in}

\headerA{
1019\\
Sixth Edition\\
}

\headerB{
Fire Dynamics Simulator\\
User's Guide\\
}

\normalsize

\headerC{
\authortitlesigs
}

\vfill

\headerD{1019}

\vfill

\logosigs

\end{minipage}

\newpage

\hspace{5in}

\newpage

\begin{minipage}[t][9in][s]{6.25in}

\headerA{
1019\\
Sixth Edition\\}

\headerB{
Fire Dynamics Simulator\\
User's Guide\\
}

\headerC{
\authorsigs
}

\headerD{1019}

\headerC{
\today \\
Revision:~\gitrevision}


\vfill

\begin{flushright}
\includegraphics[width=1in]{../Bibliography/doc}
\end{flushright}

\titlesigs

\end{minipage}

\newpage

\disclaimer{1019}

\frontmatter

\pagestyle{plain}
\pagenumbering{roman}

\input{../Bibliography/authors}


\chapter{Preface}

This Guide describes how to use the Fire Dynamics Simulator (FDS). Because new features are added periodically, check
the current version number on the inside front jacket of this manual.

Note that this Guide does not provide the background theory for FDS. A four volume set of companion documents, referred to
collectively as the FDS Technical Reference Guide~\cite{FDS_Tech_Guide}, contains details about the governing
equations and numerical methods, model verification, experimental validation, and configuration management.
The FDS User's Guide contains limited information on how to operate Smokeview, the companion
visualization program for FDS. Its full capability is described in the Smokeview User's Guide~\cite{Smokeview_Users_Guide}.


% \chapter{Disclaimer}
\input{../Bibliography/disclaimer}


\chapter{Acknowledgments}

The Fire Dynamics Simulator, in various forms, has been under development for almost 25 years. It was first released to the public in 2000. Since then, continued improvements have been made to the software based largely on feedback from its users. Included below are some who made important contributions related to the application of FDS.
\begin{itemize}
\item At NIST, Dan Madrzykowski, Doug Walton, Bob Vettori, Dave Stroup, Steve Kerber, Nelson Bryner, and Adam Barowy have used FDS and Smokeview as part of several investigations of fire fighter line of duty deaths. They have provided valuable information on the model's usability and accuracy when compared to large scale measurements made during fire reconstructions.
\item Bryan Klein of Thunderhead Engineering assisted in adding cross-referencing functionality to this document, making it easier to view electronically. He also designed the on-line services for revision control, bug reporting, and general discussion of topics related to FDS.
\item At VTT, Joonas Ryyn\"{a}nen implemented and documented the FED/FIC routine.
\item The US Nuclear Regulatory Commission has provided financial support for the verification and validation of FDS, along with valuable insights into how fire models are used as part of probabilistic risk assessments of nuclear facilities. Special thanks to Mark Salley and Dave Stroup.
\item The Society of Fire Protection Engineers (SFPE) sponsors a training course on the use of FDS and Smokeview. Chris Wood of ArupFire, Dave Sheppard of the US Bureau of Alcohol, Tobacco and Firearms (ATF), and Doug Carpenter of Combustion Science and Engineering developed the materials for the course, along with Morgan Hurley of the SFPE.
\item David McGill of Seneca College, Ontario, Canada has conducted a remote-learning course on the use of FDS, and he has also maintained a web site that has provided valuable suggestions from users.
\item Paul Hart of Swiss Re, GAP Services, and Pravinray Gandhi of Underwriters Laboratories provided useful suggestions about water droplet transport on solid objects.
\item Fran\c{c}ois Demouge of the Centre Scientifique et Technique du B\^{a}timent (CSTB) in France assisted with implementation of synthetic turbulence inflow boundary conditions.
\item Max Gould, Summer Undergraduate Research Fellow, assisted in the testing and verification of non-standard boundary treatment methods.
\end{itemize}
Finally, on the following pages is a list of individuals and organizations who have volunteered their time and effort to
``beta test'' FDS and Smokeview prior to its official release. Their contribution is invaluable because there is simply no other way
to test all of the various features of the model.

\newpage

\begin{longtable}{|l|l|}
\hline
\multicolumn{2}{|c|}{\bf FDS 6 Beta Testers} \\ \hline \hline
Mohammed Assal                          & CFD Algeria                                                               \\ \hline
Choon-Bum Choi                          & Building and Tunnel Technologies Inc. (BNTTEK), Korea                     \\ \hline
William J. Ferrante                     & Roosevelt Fire District, Hyde Park, New York, USA                         \\ \hline
Emanuele Gissi                          & Corpo nazionale dei Vigili del Fuoco, Italy                               \\ \hline
Timothy M. Groch                        & Engineering Planning and Management, Inc., Framingham, Massachusetts, USA \\ \hline
Georges Guigay                          & Mannvit Engineering, Iceland                                              \\ \hline
Simon J. Ham                            & Fire Safety Engineering Consultants Limited, UK                           \\ \hline
Chris Lautenberger                      & Reax Engineering, Berkeley, California, USA                               \\ \hline
Tim McDonald                            & Endress Ingenieurgesellschaft mbH, Germany                                \\ \hline
Dave McGill                             & Seneca College, Ontario, Canada                                           \\ \hline
Adrian Milford                          & Sereca Fire Consulting Ltd., British Columbia, Canada                     \\ \hline
Luca Nassi                              & National Fire Department, Italy                                           \\ \hline
Stephen Olenick                         & Combustion Science and Engineering, Inc., Columbia, Maryland, USA         \\ \hline
Natalie Ong                             & Arup Fire Singapore                                                       \\ \hline
Chris Salter                            & Hoare Lea and Partners, UK                                                \\ \hline
Joakim Sandstr\"{o}m                    & LTU/Brandskyddslaget, Sweden                                              \\ \hline
Julio Cesar Silva                       & Federal University of Rio de Janeiro, Brazil                              \\ \hline
Boris Stock                             & BFT Cognos GmbH, Aachen, Germany                                          \\ \hline
Csaba Szilagyi                          & OPTOMM Ltd., Budapest, Hungary                                            \\ \hline
Giacomo Villi                           & Universit\`{a} di Padova, Italy                                           \\ \hline
Andreas Vischer                         & Wijnveld//Ingenieure, Osnabr\"{u}ck, Germany                              \\ \hline
Christopher Wood                        & FireLink, LLC, Tewksbury, Massachusetts, USA                              \\ \hline
\end{longtable}

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Contents}
\tableofcontents

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{List of Figures}
\listoffigures

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{List of Tables}
\listoftables


\mainmatter



\part{The Basics of FDS}


\chapter{Introduction}

The software described in this document, Fire Dynamics Simulator (FDS), is a computational fluid dynamics (CFD) model of fire-driven fluid flow. FDS solves numerically a form of the Navier-Stokes equations appropriate for low-speed (Ma < 0.3), thermally-driven flow with an emphasis on smoke and heat transport from fires. The formulation of the equations and the numerical algorithm are contained in the FDS Technical Reference Guide~\cite{FDS_Math_Guide}. Verification and Validation of the model are discussed in the FDS Verification~\cite{FDS_Verification_Guide} and Validation~\cite{FDS_Validation_Guide} Guides.

Smokeview is a separate visualization program that is used to display the results of an FDS simulation. A detailed description of Smokeview is found in a separate user's guide~\cite{Smokeview_Users_Guide}.


\section{Features of FDS}

The first version of FDS was publicly released in February 2000. To date, about half of the applications of the model have been for design of smoke handling systems and sprinkler/detector activation studies. The other half consist of residential and industrial fire reconstructions. Throughout its development, FDS has been aimed at solving practical fire problems in fire protection engineering, while at the same time providing a tool to study fundamental fire dynamics and combustion.

\begin{description}
\item[Hydrodynamic Model] FDS solves numerically a form of the Navier-Stokes equations appropriate for low-speed, thermally-driven flow with an emphasis on smoke and heat transport from fires. The core algorithm is an explicit predictor-corrector scheme, second order accurate in space and time. Turbulence is treated by means of Large Eddy Simulation (LES). It is possible to perform a Direct Numerical Simulation (DNS) if the underlying numerical mesh is fine enough. LES is the default mode of operation.
\item[Combustion Model] For most applications, FDS uses a single step, mixing-controlled chemical reaction which uses three lumped species (a species representing a group of species). These lumped species are air, fuel, and products. By default the last two lumped species are explicitly computed. Options are available to include multiple reactions and reactions that are not necessarily mixing-controlled.
\item[Radiation Transport] Radiative heat transfer is included in the model via the solution of the radiation transport equation for a gray gas, and in some limited cases using a wide band model. The equation is solved using a technique similar to finite volume methods for convective transport, thus the name given to it is the Finite Volume Method (FVM).  Using approximately 100 discrete angles, the finite volume solver requires about 20~\% of the total CPU time of a calculation, a modest cost given the complexity of radiation heat transfer. The absorption coefficients of the gas-soot mixtures are computed using the RadCal narrow-band model~\cite{RadCal}.  Liquid droplets can absorb and scatter thermal radiation. This is important in cases involving mist sprinklers, but also plays a role in all sprinkler cases.  The absorption and scattering coefficients are based on Mie theory.
\item[Geometry] FDS approximates the governing equations on a rectilinear mesh. Rectangular obstructions are forced to conform with the underlying mesh.
\item[Multiple Meshes] This is a term used to describe the use of more than one rectangular mesh in a calculation. It is possible to prescribe more than one rectangular mesh to handle cases where the computational domain is not easily embedded within a single mesh.
\item[Parallel Processing] FDS employs OpenMP~\cite{Chapman:OpenMP}, a programming interface that exploits multiple processing units on a single computer. For clusters of computers, FDS employs Message Passing Interface (MPI)~\cite{Gropp:1}. Details can be found in Section~\ref{info:parallelprocessing}.
\item[Boundary Conditions] All solid surfaces are assigned thermal boundary conditions, plus information about the burning behavior of the material. Heat and mass transfer to and from solid surfaces is usually handled with empirical correlations, although it is possible to compute directly the heat and mass transfer when performing a Direct Numerical Simulation (DNS).
\end{description}


\section{What's New in FDS 6?}

Many of the changes in FDS~6 are improvements to the various sub-models that do not affect the basic structure or parameters of the input file. Most of the changes listed below do not require additional input parameters beyond those used in FDS~5.

\subsubsection{Hydrodynamics and Turbulence}

   \begin{itemize}
   \item Conservative, total variation diminishing (TVD) scalar transport is implemented: Superbee (LES default) and CHARM (DNS default). These schemes prevent over-shoots and under-shoots in species concentrations and temperature.
   \item Improved models for the turbulent viscosity are implemented: Deardorff (default), Dynamic Smagorinsky, and Vreman. These models provide more dynamic range to the flow field for coarse resolution and converge to the correct solution at fine resolution.
   \item The conservative form of the sensible enthalpy equation is satisfied by construction in the FDS~6 formulation, eliminating temperature anomalies and energy conservation errors due to numerical mixing.
   \item The baroclinic torque is included by default.
   \item Improvements are made to the wall functions for momentum and heat flux. An optional wall heat flux model accounts for variable Prandtl number fluids.
   \item Jarrin's Synthetic Eddy Method (SEM) is implemented for turbulent boundary conditions at vents.
   \end{itemize}

\subsubsection{Species and Combustion}

    \begin{itemize}
    \item Custom species mixtures (``lumped species'') can be defined with the input group SPEC.
    \item Turbulent combustion is handled with a new partially-stirred batch reactor model. At the subgrid level, species exist in one of two states: unmixed or mixed. The degree of mixing evolves over the FDS time step by the interaction by exchange with the mean (IEM) mixing model. Chemical kinetics may be considered infinitely fast or obey an Arrhenius rate law.
    \item It is now possible to transport, produce, and consume product species such as CO and soot. Chemical mechanisms must be provided by the user and may include reversible reactions.
    \item It is now possible to deposit aerosol species onto surfaces.
    \item There are an increased number of predefined species that now include liquid properties.
    \end{itemize}

\subsubsection{Lagrangian Particles}

    \begin{itemize}
    \item The functionality of Lagrangian particles has expanded to include the same heat transfer and pyrolysis models that apply to solid walls. In other words, you can now assign a set of surface properties to planar, cylindrical, or spherical particles much like you would for a solid surface.
    \item More alternatives and user-defined option are available for the liquid droplet size distribution.
    \item You can specify the radiative properties of the liquid droplets.
    \item Drag effects of thin porous media (i.e., window screens) can be simulated using planes of particles.
    \end{itemize}

\subsubsection{Solid Phase Heat Transfer and Pyrolysis}

    \begin{itemize}
    \item The basic 1-D heat transfer and pyrolysis model for solid surfaces remains the same, but there has been a change in several of the input parameters to expand functionality and readability of the input file.
    \item The pyrolysis model allows for the surface to shrink or swell, based on the specified material densities.
    \end{itemize}

\subsubsection{HVAC}

   \begin{itemize}
    \item Filters, louvered vents, and heating/cooling capability has been added for HVAC systems.
    \item HVAC is now functional with MPI.
    \end{itemize}

\subsubsection{Radiation}

    \begin{itemize}
    \item RadCal database has been extended to include additional fuel species.
    \item In cells with heat release, the emission term is based on a corrected $\sigma \, T^4$ such that when this term is integrated over the flame volume the specified radiative fraction (default 0.35) is recovered. This differs from FDS~5 and earlier where the radiative fraction times the heat release rate was applied locally as the emission term.
    \end{itemize}

\subsubsection{Multi-Mesh Computations}

    \begin{itemize}
    \item By default, FDS now iterates pressure and velocity at mesh and solid boundaries. You can control the error tolerance and maximum number of iterations via parameters on the {\ct PRES} line.
    \end{itemize}

\subsubsection{Control Functions}

    \begin{itemize}
    \item {\ct CTRL} functions have been extended to include math operations.
    \item The evaluation of {\ct RAMP}s and {\ct DEVC}s can be stopped, freezing their value, based upon the activation of a device or control function.
    \end{itemize}

\subsubsection{Devices and Output}

    \begin{itemize}
    \item Multiple pipe networks can be specified for sprinklers for reduction of flow rate based on the number of operating heads.
    \item The numerical value of a control function can be output with a {\ct DEVC}.
    \item A line of devices can be specified using a number of {\ct POINTS} on one {\ct DEVC} line.
    \item Statistical outputs for RMS, covariance, and correlation coefficient are available.
    \end{itemize}





\section{Changes to Input Parameters in FDS 6}

This section describes the changes in the input parameters between FDS version~5 and version~6. Table~\ref{tbl:Changes} lists in alphabetical order parameters from FDS~5 that have changed. Note that this table does not list new parameters in FDS~6.

There has been a limited amount of backward compatibility programmed into FDS 6. In other words, several commonly used parameters and conventions from previous versions still
work, but you are encouraged to gradually modify your input files to conform to the new conventions. Gradually, obsolescent features will be removed. Some of the more notable changes
in FDS 6 are:
\begin{itemize}
\item If you want to model a fire, you {\em must} include a {\ct REAC} line with a specified {\ct FUEL}. See Chapter~\ref{info:REAC} for details.
\item The output quantity {\ct 'MIXTURE\_FRACTION'} has been replaced with {\ct 'MIXTURE FRACTION'} and is only usable if there is a single {\ct REAC} input of the form ${\rm A} \; + \; {\rm B} \rightarrow {\rm C}$ and {\ct INITIAL\_UNMIXED\_FRACTION=0}.
\item There is no longer a {\ct STATE\_FILE} because there is no longer a simple mixture fraction model.
\item {\ct PRESSURE\_CORRECTION} has been eliminated. See Section~\ref{info:PRES} for ways to improve the performance of the pressure solver.
\item Species mass and volume fraction outputs are no longer invoked using {\ct QUANTITY='species name'}. Use {\ct QUANTITY='MASS FRACTION'} or {\ct QUANTITY='VOLUME FRACTION'} along with {\ct SPEC\_ID} instead.  Also note that all predefined species (Table~\ref{tab:gasspecies}) are now referenced with all uppercase letters.
\item The output quantity {\ct 'SOOT VOLUME FRACTION'} is now {\ct 'AEROSOL VOLUME FRACTION'} along with {\ct SPEC\_ID} to identify the name of the species.
\end{itemize}


\begin{sidewaystable}[p]
\caption[List of changes to input parameters for FDS 6]{Changes to input parameters, FDS version 5 to 6.}
\label{tbl:Changes}
\centering
\begin{tabular}{@{\extracolsep{\fill}}|c|l|c|l|l|}
\hline
Namelist  & FDS 5 Parameter & Namelist  & FDS 6 Parameter & Notes \\ \hline \hline
{\ct BNDF}    & {\ct RECOUNT\_DRIP}                 &              & Eliminated                                  &                                              \\ \hline
{\ct CLIP}    & {\ct MAXIMUM\_MASS\_FRACTION}       &              & Eliminated                                  & Section~\ref{info:CLIP}                      \\ \hline
{\ct CLIP}    & {\ct MINIMUM\_MASS\_FRACTION}       &              & Eliminated                                  &  Section~\ref{info:CLIP}                     \\ \hline
{\ct DUMP}    & {\ct MAXIMUM\_DROPLETS}             &  {\ct DUMP}  &  {\ct MAXIMUM\_PARTICLES}                   &  Section~\ref{info:DUMP}                  \\ \hline
{\ct DUMP}    & {\ct STATE\_FILE}                   &              & Eliminated                                  &                                              \\ \hline
{\ct INIT}    & {\ct NUMBER\_INITIAL\_DROPLETS}     &  {\ct INIT}  &  {\ct N\_PARTICLES},  {\ct N\_PARTICLES\_PER\_CELL} &  Section~\ref{info:initial_droplets}                  \\ \hline
{\ct MATL}    & {\ct NU\_FUEL}                      &  {\ct MATL}  & {\ct NU\_SPEC} +  {\ct SPEC\_ID}            & Section~\ref{info:solid_pyrolysis}       \\ \hline
{\ct MATL}    & {\ct NU\_GAS}                       &  {\ct MATL}  & {\ct NU\_SPEC} +  {\ct SPEC\_ID}            & Section~\ref{info:solid_pyrolysis}       \\ \hline
{\ct MATL}    & {\ct NU\_RESIDUE}                   &  {\ct MATL}  & {\ct NU\_MATL}                              & Section~\ref{info:solid_pyrolysis}       \\ \hline
{\ct MATL}    & {\ct NU\_WATER}                     &  {\ct MATL}  & {\ct NU\_SPEC} +  {\ct SPEC\_ID}            & Section~\ref{info:solid_pyrolysis}       \\ \hline
{\ct MATL}    & {\ct RESIDUE}                       &  {\ct MATL}  & {\ct MATL\_ID}                              & Section~\ref{info:solid_pyrolysis}       \\ \hline
{\ct MISC}    & {\ct BACKGROUND\_SPECIES}           &  {\ct SPEC}  & {\ct BACKGROUND=.TRUE.}                     & Section~\ref{info:SPEC}                  \\ \hline
{\ct MISC}    & {\ct CONDUCTIVITY}                  &  {\ct SPEC}  & {\ct CONDUCTIVITY}                          & Section~\ref{info:SPEC}                  \\ \hline
{\ct MISC}    & {\ct CO\_PRODUCTION}                &              & New procedure                               & Section~\ref{info:finite}                \\ \hline
{\ct MISC}    & {\ct CSMAG}                         &  {\ct MISC}  & {\ct C\_SMAGORINSKY}                        & Section~\ref{info:LES}                   \\ \hline
{\ct MISC}    & {\ct MW}                            &  {\ct SPEC}  & {\ct MW}                                    & Section~\ref{info:SPEC}                  \\ \hline
{\ct MISC}    & {\ct PRESSURE\_CORRECTION}          &  {\ct PRES}  & {\ct VELOCITY\_TOLERANCE}                   & Section~\ref{info:PRES}                  \\ \hline
{\ct MISC}    & {\ct RADIATION}                     &  {\ct RADI}  & {\ct RADIATION}                             & Section~\ref{info:RADI}                  \\ \hline
{\ct MISC}    & {\ct EVAC\_SURF\_DEFAULT}           &  {\ct SURF}  & {\ct EVAC\_DEFAULT}                         & Section~\ref{info:SURF}                  \\ \hline
{\ct MISC}    & {\ct SURF\_DEFAULT}                 &  {\ct SURF}  & {\ct DEFAULT}                               & Section~\ref{info:SURF}                  \\ \hline
{\ct MISC}    & {\ct VISCOSITY}                     &  {\ct SPEC}  &  {\ct VISCOSITY}                            & Section~\ref{info:SPEC}                  \\ \hline
{\ct OBST}    & {\ct SAWTOOTH}                      &  {\ct SURF}  & Eliminated                                  & Section~\ref{info:WALL_MODEL}            \\ \hline
{\ct PART}    & {\ct FUEL}                          &  {\ct PART}  & {\ct SPEC\_ID='[FUEL]'}                     & Section~\ref{info:fuel_droplets}         \\ \hline
{\ct PART}    & {\ct HEAT\_OF\_VAPORIZATION}        &  {\ct SPEC}  &  {\ct HEAT\_OF\_VAPORIZATION}               & Section~\ref{thermal_part_props}         \\ \hline
{\ct PART}    & {\ct H\_V\_REFERENCE\_TEMPERATURE}  &  {\ct SPEC}  &   {\ct H\_V\_REFERENCE\_TEMPERATURE}        & Section~\ref{thermal_part_props}         \\ \hline
{\ct PART}    & {\ct MELTING\_TEMPERATURE}          &  {\ct SPEC}  & {\ct MELTING\_TEMPERATURE}                  & Section~\ref{thermal_part_props}         \\ \hline
{\ct PART}    & {\ct NUMBER\_INITIAL\_DROPLETS}     &  {\ct INIT}  & {\ct N\_PARTICLES}                          & Section~\ref{info:initial_droplets}      \\ \hline
{\ct PART}    & {\ct PARTICLES\_PER\_SECOND}        &  {\ct PROP}  & {\ct PARTICLES\_PER\_SECOND}                & Section~\ref{info:sprinkler_droplets}    \\ \hline
\end{tabular}
\end{sidewaystable}

\begin{sidewaystable}[p]
\caption[List of changes to input parameters for FDS 6 (continued)]{Changes to input parameters, FDS version 5 to 6 (continued).}
\label{tbl:Changes2}
\centering
\begin{tabular}{@{\extracolsep{\fill}}|c|l|c|l|l|}
\hline
Namelist      & FDS 5 Parameter                     & Namelist     & FDS 6 Parameter & Notes \\ \hline \hline
{\ct PART}    & {\ct SPECIFIC\_HEAT}                &  {\ct SPEC}  & {\ct SPECIFIC\_HEAT\_LIQUID}                & Section~\ref{thermal_part_props}        \\ \hline
{\ct PART}    & {\ct VAPORIZATION\_TEMPERATURE}     &  {\ct SPEC}  & {\ct VAPORIZATION\_TEMPERATURE}             & Section~\ref{thermal_part_props}        \\ \hline
{\ct PART}    & {\ct WATER}                         &  {\ct PART}  & {\ct SPEC\_ID='WATER VAPOR'}                & Section~\ref{info:PART_Basics}          \\ \hline
{\ct PROP}    & {\ct CABLE\_DIAMETER}               &              & New procedure                               & Section~\ref{info:THIEF}                \\ \hline
{\ct PROP}    & {\ct CABLE\_FAILURE\_TEMPERATURE}   &              & New procedure                               & Section~\ref{info:THIEF}                \\ \hline
{\ct PROP}    & {\ct CABLE\_JACKET\_THICKNESS}      &              & New procedure                               & Section~\ref{info:THIEF}                \\ \hline
{\ct PROP}    & {\ct CABLE\_MASS\_PER\_LENGTH}      &              & New procedure                               & Section~\ref{info:THIEF}                \\ \hline
{\ct PROP}    & {\ct CONDUIT\_DIAMETER}             &              & New procedure                               & Section~\ref{info:THIEF}                \\ \hline
{\ct PROP}    & {\ct CONDUIT\_THICKNESS}            &              & New procedure                               & Section~\ref{info:THIEF}                \\ \hline
{\ct PROP}    & {\ct DROPLETS\_PER\_SECOND}         &  {\ct PROP}  & {\ct PARTICLES\_PER\_SECOND}                & Section~\ref{info:sprinkler_droplets}   \\ \hline
{\ct PROP}    & {\ct DROPLET\_VELOCITY}             &  {\ct PROP}  & {\ct PARTICLE\_VELOCITY}                    & Section~\ref{info:sprinklers}           \\ \hline
{\ct PROP}    & {\ct DT\_INSERT}                    &              & New procedure                               & Section~\ref{info:controlling_droplets} \\ \hline
{\ct RADI}    & {\ct CH4\_BANDS}                    &              & Eliminated                                  &                                         \\ \hline
{\ct RADI}    & {\ct RADIATIVE\_FRACTION}           &  {\ct REAC}  & {\ct RADIATIVE\_FRACTION}                   & Section ~\ref{info:CHI_R}               \\ \hline
{\ct REAC}    & {\ct BOF}                           &  {\ct REAC}  & {\ct A}                                     & Section~\ref{info:finite}               \\ \hline
{\ct REAC}    & {\ct ID}                            &  {\ct REAC}  & {\ct FUEL}                                  & Section~\ref{info:simple_chemistry}     \\ \hline
{\ct REAC}    & {\ct MASS\_EXTINCTION\_COEFFICIENT} &  {\ct SPEC}  & {\ct MASS\_EXTINCTION\_COEFFICIENT}         & Section~\ref{info:visibility}           \\ \hline
{\ct REAC}    & {\ct MAXIMUM\_VISIBILITY}           &  {\ct MISC}  & {\ct MAXIMUM\_VISIBILITY}                   & Section~\ref{info:visibility}           \\ \hline
{\ct REAC}    & {\ct OXIDIZER}                      &              & New procedure                               & Section~\ref{info:REAC_Diagnostics}     \\ \hline
{\ct REAC}    & {\ct VISIBILITY\_FACTOR}            &  {\ct MISC}  & {\ct VISIBILITY\_FACTOR}                    & Section~\ref{info:visibility}           \\ \hline
{\ct SPEC}    & {\ct ABSORBING}                     &  {\ct SPEC}  & {\ct RADCAL\_ID }                           & Section~\ref{info:radiative_spec_props} \\ \hline
{\ct SURF}    & {\ct H\_FIXED}                      &  {\ct SURF}  & {\ct HEAT\_TRANSFER\_COEFFICIENT}           & Section~\ref{info:convection}           \\ \hline
{\ct SURF}    & {\ct POROUS}                        &              & New procedure                               & Section~\ref{info:HVACfan}              \\ \hline
{\ct SURF}    & {\ct VOLUME\_FLUX}                  &  {\ct SURF}  & {\ct VOLUME\_FLOW}                          & Section~\ref{info:MASS_FLUX}            \\ \hline
{\ct TIME}    & {\ct TWFIN}                         &  {\ct TIME}  & {\ct T\_END}                                & Section~\ref{info:TIME}                 \\ \hline
{\ct VENT}    & {\ct MASS\_FRACTION}                &              & Eliminated                                  &                                         \\ \hline
\end{tabular}
\end{sidewaystable}


\section{A Note on Longer Run Times in FDS 6}

A number of changes made in FDS 6 are aimed at improving the robustness and accuracy of the simulations. However, these improvements come at increased cost in both CPU time and memory usage. Some of this increased cost is offset by increasingly faster computers and improved parallel processing. In particular, starting with FDS~6.1.0, the default released version of FDS will employ OpenMP~\cite{Chapman:OpenMP} by default. OpenMP is a programming interface that enables FDS to exploit multiple processing units on a given computer. Most Windows-based personal computers now come with multi-core processors, but past versions of FDS could only exploit a single core for a given calculation. With this new release and the increasingly faster processors available on the market, FDS~6 ought to maintain and eventually surpass the computing speed of past versions.

Listed below are suggested ways to decrease CPU time, but these options should be considered very carefully. The default parameter settings are designed to address a wide range of fire scenarios, but there are scenarios for which approximations used in past versions of FDS may still be appropriate. The best way to determine if one or more of these time-saving assumptions is appropriate, run identical simulations with and without the assumption to determine if the difference in results is acceptable.

\begin{enumerate}
\item The improved turbulence model in FDS 6 has been found to produce comparable results to older versions of FDS using slightly less refined numerical grids. Section~\ref{info:Mesh_Resolution} introduces a dimensionless parameter, $D^*/\dx$, that indicates the number of grid cells of dimension $\dx$ that span the characteristic width of the fire, $D^*$. A grid resolution study should be performed to determine the loss of accuracy caused by a reduced value of $D^*/\dx$.
\item One reason for the increased CPU cost of FDS~6 is the more precise treatment of gas species properties. Previous versions of FDS assumed that the specific heat of a gas species is solely dependent on its molecular weight, and that the ratio of specific heats, $c_p/c_v$, is equal to 1.4, a value appropriate for a diatomic gas like nitrogen, N$_2$. Section~\ref{info:Enthalpy} provides more details. FDS~6 now assumes that gas species are temperature-dependent, and this assumption increases the cost of the calculation in a number of different routines, in particular the calculation of the divergence. If you set {\ct CONSTANT\_SPECIFIC\_HEAT\_RATIO=.TRUE.} on the {\ct MISC} line together with {\ct STRATIFICATION=.FALSE.} on the {\ct WIND} line and {\ct EXTINCTION\_MODEL = 'EXTINCTION 1'}  or {\ct SUPPRESSION=.FALSE.} on the {\ct COMB} line, you can once again assume that the gas species are all diatomic. For scenarios where the overall compartment temperature does not approach flashover conditions, this assumption might be appropriate.
\item In situations where you are simulating a relatively small fire in a relatively large space and you are not interested in heat fluxes to surrounding structures, it might be reasonable to turn off the radiation transport calculation by setting {\ct RADIATION} equal to {\ct .FALSE.} on the {\ct RADI} line. FDS will still assume that a fixed fraction of the fire's energy is radiated away, only now the energy is simply removed from the calculation.
\item In situations where the heat transfer conditions are stationary or change only gradually, you can reduce the cost of the radiation solution by reducing the temporal resolution. More details in Section~\ref{info:RADI_Resolution}. A sensitivity study should be performed to determine the loss of accuracy.
\end{enumerate}










\chapter{Getting Started}
\label{info:gettingstarted}

FDS is a computer program that solves equations that describe the evolution of fire. It is a Fortran program that reads input parameters from a text file, computes a numerical solution to the governing equations, and writes user-specified output data to files. Smokeview is a companion program that reads FDS output files and produces animations on the computer screen. Smokeview has a simple menu-driven interface. FDS does not. However, there are various third-party programs that have been developed to generate the text file containing the input parameters needed by FDS.

This guide describes how to obtain FDS and Smokeview and how to use FDS. A separate document~\cite{Smokeview_Users_Guide} describes how to use Smokeview.

\section{How to Acquire FDS and Smokeview}
\label{info:acquire}

Detailed instructions on how to download executables, manuals, source-code and related utilities, can be found at the project home page:

\begin{center}
\href{https://pages.nist.gov/fds-smv/}{{\ct https://pages.nist.gov/fds-smv/}}
\end{center}

\noindent
The typical FDS/Smokeview distribution consists of an installation package or compressed archive, which is available for MS Windows, Mac~OS~X, and Linux.

If you ever want to keep an older version of FDS and Smokeview, copy the installation directory to some other place so that it is not overwritten during the updated installation.


\section{Computer Hardware Requirements}

The only hard requirement to run the compiled versions of FDS and Smokeview is a 64~bit Windows, Linux, or Mac OS X operating system. The single computer or compute cluster ought to have fast processors (CPUs), and at least 2 to 4~GB RAM per core. The CPU speed will determine how long the computation will take to finish, while the amount of RAM will determine how many mesh cells can be held in memory. A large hard drive is required to store the output of the calculations. It is not unusual for the output of a single calculation to consume more than 10~GB of storage space.

Most computers purchased within the past few years are adequate for running Smokeview with the caveat that additional memory (RAM) should be purchased to bring the memory size up to at least 2~GB. This is so the computer can display results without ``swapping'' to disk. For Smokeview it is also important to obtain a fast graphics card for the PC used to display the results of the FDS computations.

Running FDS using MPI requires shared disk access to each computer where cases will be run.  On Windows systems this involves a domain network with the ability to share folders.  On a Linux or Mac~OS~X system this involves NFS cross mounted files systems with ssh keys setup for passwordless login. For Multi-Mesh calculations, the FDS can operate over standard 100~Mb/s networks. A gigabit (1000~Mb/s) network will further reduce network communication times improving data transfer rates between instances of FDS running the parallel cases.


\section{Computer Operating System (OS) and Software Requirements}

The goal of making FDS and Smokeview publicly available has been to enable practicing engineers to perform fairly sophisticated simulations at a reasonable cost. Thus, FDS and Smokeview have been designed for computers running Microsoft Windows, Mac OS~X, and Linux.
\begin{description}
\item[{\bf MS Windows}] An installation package is available for the 64~bit Windows operating system. It is not recommended to run FDS/Smokeview under any version of MS Windows released prior to Windows 7.
\item[{\bf Mac OS X}] Pre-compiled executables are installed into a user selected directory using an installation script.  Mac OS~X 10.4.x or better is recommended. You can always download the latest version of FDS source and compile FDS for other versions of OS~X (See Appendix~\ref{info:compilation} for details).
\item[{\bf Linux}] Pre-compiled executables are installed into a user selected directory using an installation script. If the pre-compiled FDS executable does not work (usually because of library incompatibilities), the FDS Fortran source code can be downloaded and compiled (See Appendix~\ref{info:compilation} for details). If Smokeview does not work on the Linux workstation, you can use the Windows version to view FDS output.
\end{description}

\section{Installation Testing}

If you are running FDS under a quality assurance plan that requires installation testing, a test procedure is provided in Appendix B of the FDS Verification Guide~\cite{FDS_Verification_Guide}.  This guide can be obtained from the FDS-SMV website.



\chapter{Running FDS}
\label{info:runningFDS}

Each FDS simulation is controlled by a single text-based input file, typically given a name that helps identify the particular case, and ending with the file extension {\ct .fds}. This input file can be written directly with a text editor or with the help of a third-party graphical user interface (GUI). The simulation is started directly via the command prompt or through the GUI. The creation of an input file is covered in detail in Part~\ref{info:inputfilecreation}. This chapter describes how the simulation is run once the input file is written.

If you are new to FDS and Smokeview, it is strongly suggested that you start with an existing input file, run it as is, and then make the appropriate changes to the file for your desired scenario. By running a sample case, you become familiar with the procedure, learn how to use Smokeview, and ensure that your computer is up to the task before embarking on learning how to create new input files.

Sample input files are included as part of the standard installation. A good case for a first time user is located in the subfolder called {\ct Fires} within the folder called {\ct Examples}. Find the file called \linebreak[4]{\ct simple\_test.fds} and copy it to a folder on your computer that is not within the installation folder. The reason for doing this is to avoid cluttering up the installation folder with a lot of output files. Follow the instructions in Section~\ref{single_mesh} to run this simple single mesh case. The simulation should only take a few minutes. Once the simulation is completed, use Smokeview to examine the output. In this way, you will quickly learn the basics of running and analyzing simulations.


\section{Computer Basics}

\subsection{A Brief Primer on Computer Hardware}

FDS simulations can exploit multiple processing units on a single computer or multiple computers on a network. Before running an FDS simulation, you should familiarize yourself with your computer hardware. 

If you are using a computer running Microsoft Windows, open up the Task Manager, Performance tab, and look for the number of {\em sockets}, {\em cores}, and {\em logical processors}\footnote{The terms sockets, cores, and logical processors are used by the Windows~10 Task Manager on a computer using an Intel processor. These terms might vary with different versions of Windows and different processors.}. The socket refers to the physical connector on the motherboard that has a power supply and a connection to random access memory (RAM). This is usually referred to as the central processing unit or CPU. Some motherboards have multiple sockets that can in turn support multiple CPUs, but for typical Windows desktops or laptops, there is one socket/CPU. Each CPU, however, typically has multiple cores, and each core is essentially an independent processing unit that shares access to power and memory. Sometimes cores are referred to as {\em physical cores} to distinguish them from {\em logical cores} or {\em logical processors}. A logical processor is one of multiple {\em threads} that can be supported by a core. For the purpose of running FDS on a Windows computer, the number of logical processors is your most important consideration.

If you are running FDS under any variety of Linux or Mac~OS~X, you can determine the number of logical processors using the command ``lscpu'' for Linux or ``sysctl hw'' for OS~X. These operating systems might use slightly different terms, but the processors are similar if not the same as those on a Windows computer.


\subsection{Two Ways to Use Multiple Processors}

FDS can be run on a single computer, using one or more cores, or it can be run on multiple computers. Starting with FDS version~6.2.0, for each supported operating system (Windows, Linux, Mac~OS~X) there is a single\footnote{Previous releases of FDS contained two executables, one that ran on a single processor and one that ran on multiple processors. Starting with FDS~6.2.0, these two executables have been combined into one, and it can run either in serial or parallel mode.} executable file called {\ct fds} (with an {\ct .exe}\ file extension on Windows).

There are two ways that FDS can be run in parallel; that is, exploit multiple cores on a single computer or multiple processors/cores distributed over multiple computers on a network or compute cluster. The first way is OpenMP (Open Multi-Processing)~\cite{Chapman:OpenMP} which allows a single computer to run a single or multiple mesh FDS simulation on multiple cores. The use of OpenMP does not require the computational domain to be broken up into multiple meshes, and it will still work with cases that have multiple meshes defined. The second way to run FDS in parallel is by way of MPI (Message Passing Interface). Here, the computational domain must be divided into multiple meshes and typically each mesh is assigned its own {\em process}. These processes can be limited to a single computer, or they can be distributed over a network.



\subsubsection{What is OpenMP?}
\label{single_mesh}

If your simulation involves only one mesh, you can only run it on one computer, but you can exploit its multiple processors or cores using OpenMP. When you install FDS, it will query your computer to determine the number of available cores. By default, FDS will use approximately half of the available cores\footnote{To determine the number of cores used by OpenMP, just type {\ct fds} at the command prompt.} on a single computer. This is done for two reasons: (1) so as not to take over your entire machine when you run a simulation, and (2) because using all cores for a single simulation may not minimize the run time. OpenMP works best when exploiting multiple (logical) cores associated with a single (physical) processor or ``socket''.  For example, if your computer has two processors, each with 4 cores, it may not be worthwhile to use all 8 cores in an OpenMP simulation. You need to experiment with your own machine to determine the strategy that is best for you. To change the number of cores that are available for a given FDS simulation, you can set an environment variable called {\ct OMP\_NUM\_THREADS}. The way to do this depends on the operating system and will be explained below.

When the job is started, FDS will print the number of cores that will be used for that job. Note that this setting only applies until you log out or restart your machine. To set the default value of available cores upon startup, the {\ct OMP\_NUM\_THREADS} environment variable can also be set in the startup configuration scripts on the machine. Refer to the documentation for your operating system for more information on how to configure environment variables upon startup.

\subsubsection{What is MPI?}
\label{info:parallelprocessing}

MPI (Message-Passing Interface)~\cite{Gropp:1} enables multiple computers, or multiple cores on one computer, to run a multi-mesh FDS job. The main idea is that you must break up the FDS domain into multiple meshes, and then the flow field in each mesh is computed as an MPI {\em process.}  The {\em process} can be thought of as a ``task'' that you would see in the Windows Task Manager or by executing the ``top'' command on a Linux/Unix machine. MPI handles the transfer of information between the meshes, i.e. MPI processes. Usually, each mesh is assigned its own {\em process} in an MPI calculation, although it is also possible to assign multiple meshes to a single MPI {\em process}. In this way, large meshes can be computed on dedicated cores, while smaller meshes can be clustered together in a single {\em process} running on a single core, without the need for MPI message passing.

Also note that FDS refers to its meshes by the numbers 1, 2, 3, and so on, whereas MPI refers to its processes by the numbers 0, 1, 2, and so on. Thus, Mesh~1 is assigned to Process~0; Mesh~2 to Process~1, and so on. You do not explicitly number the meshes or the processes yourself, but error statements from FDS or from MPI might refer to the meshes or processes by number. As an example, if a FDS case with five meshes, the first printout (usually to the screen unless otherwise directed) is:
\begin{lstlisting}
Mesh   1 is assigned to MPI Process   0
Mesh   2 is assigned to MPI Process   1
Mesh   3 is assigned to MPI Process   2
Mesh   4 is assigned to MPI Process   3
Mesh   5 is assigned to MPI Process   4
\end{lstlisting}
This means that 5 MPI processes (numbered 0 to 4) have started and that each mesh is being handled by its own process. The processes may be on the same or different computers. Each computer has its own memory (RAM), but each individual MPI process has its own independent memory, even if the processes are on the same computer.

There are different implementations of MPI, much like there are different Fortran and C compilers. Each implementation is essentially a library of subroutines called from FDS that transfer data from one process to another across a fast network. The format of the subroutine calls has been widely accepted in the community, allowing different vendors and organizations the freedom to develop better software while working within an open framework. For Mac OS~X, we use Open MPI, an open source implementation that is developed and maintained by a consortium of academic, research, and industry partners (www.open-mpi.org). For Windows and Linux, we use Intel MPI~\footnote{Prior to FDS version 6.1.2, the Windows version of FDS used MPICH, a free implementation of MPI developed by Argonne National Laboratory. The MPICH developers have announced that they are no longer supporting the Windows version.}.

MPI and OpenMP can be used together. For example, 4 MPI processes can be assigned to 4 different computers, and each MPI process can be supported by, say, 8 OpenMP threads, assuming each computer has 8 cores. Most of the speed up is achieved by the MPI. For a reasonably fast network, you can expect 4 MPI processes to speed up the computation time by a factor of about 0.9 times 4. The OpenMP can provide an extra factor up to about 2, regardless of the number of cores used beyond about 4.


\section{Launching an FDS Job}

To start an FDS simulation, you can either use a third-party graphical user interface (GUI) or you can invoke the computer's command prompt and type a one-line command, as described in the following sections.

\subsubsection{MS Windows}

The files needed to run an FDS simulation on a single Windows computer or across a Windows domain network are bundled in with the FDS download. There is no need to install MPI or any redistributable libraries. The following procedure is intended for a Windows domain network; that is, a network where user accounts are centrally managed such that any user can log in to any machine using the same credentials. If you are not on a domain network, you can still run FDS locally, and instructions are given below.

First, it is a good idea to uninstall older versions of FDS from all computers you plan to use. Even though the new version will overwrite older versions, there is always a chance that some remnant of an older version might cause incompatibilities with the new.

Open up a Command Prompt window (click Start, then Run, then type ``cmd''), and change directories (``cd'') to where the input file for the case is located. Decide how many logical processes you want to devote to the simulation. For example, if you have 8 logical processes available, and you have an FDS job that involves 4 meshes, you would type the following at the command prompt:
\begin{lstlisting}
mpiexec -n 4 -env OMP_NUM_THREADS 2 fds job_name.fds
\end{lstlisting}
If you are not on a Windows domain network, add the argument {\ct -localonly} to the command line, which means that you do not intend to run the job across multiple computers and that you do not need to provide network credentials.

The progress of the simulation is indicated by diagnostic output that is written onto the screen. Detailed diagnostic information is automatically written to a file {\ct job\_name.out}. Screen output can be redirected to a file via the alternative command:
\begin{lstlisting}
mpiexec ... fds job_name.fds > job_name.err
\end{lstlisting}
Note that it is also possible to associate the {\ct .fds} extension with the FDS executable directly, thereby making FDS run by double-clicking on the input file. However, we do not recommend this because of complications associated with the {\ct mpiexec} program.

Also, you can automatically set the number of OpenMP threads via the command:
\begin{lstlisting}
set OMP_NUM_THREADS=N
\end{lstlisting}
where {\ct N} is the number of OpenMP threads to assign to each MPI process for all jobs launched during that particular session. You can change {\ct OMP\_NUM\_THREADS} permanently by changing the system environment variable of the same name.

If you wish to run FDS on more than one computer, do the following:
\begin{enumerate}
\item Type the following command:

    {\ct mpiexec -hosts 2 <my\_computer> 1 <other\_computer> 1 test\_mpi}

    If this command returns a ``Hello World'' message from your computer and the other computer on your network, proceed to the next step. If this command fails, check that you can ``see'' the other machine by pinging it, and check that the other computer can ``see'' your computer as well. Also, make sure that the same version of FDS is installed on the other computer.

\item Share (with both read and write privilege) a working directory on your machine. Do not put this directory within the ``Program Files'' folder because it is write-protected. Share the working directory with everybody so that all other computers can see it. Note how this directory is defined on the other computers. Sometimes it is {\ct \textbackslash\textbackslash<my\_computer>\textbackslash<my\_shared\_directory>\textbackslash} and sometimes it is defined via the numerical IP address, like {\ct \textbackslash\textbackslash129.6.129.87\textbackslash<my\_shared\_directory>\textbackslash}. The definition depends on the way your domain name server (DNS) works. In any case, do not leave blank spaces within any directory or file names. We have found that blanks create all sorts of trouble. Unless you are a DOS/Windows expert, avoid them.

\item Within the command prompt, {\ct cd} to the working directory. Find or create within the working directory a relatively small, simple, two mesh FDS input file. At the command prompt, type:

   {\ct mpiexec -hosts 2 fred 1 ethel 1 -wdir \textbackslash\textbackslash...\textbackslash... fds job\_name.fds}

   where {\ct fred} and {\ct ethel} are the names of two computers on your network. Remember to add the argument {\ct -env OMP\_NUM\_THREADS N} to set the number of OpenMP threads per MPI process on all computers. The default is {\em not} 1, but rather depends on the number of logical processors your computer has. If you accidently set too many OpenMP threads, you can overload your logical processors and reduce the job efficiency.

\item If successful, you should see the usual FDS printout indicating the processes being assigned to the computers. If unsuccessful, try running the case on your own machine:

   {\ct mpiexec -hosts 1 fred 2 -wdir \textbackslash\textbackslash...\textbackslash... fds job\_name.fds}

   If this is not successful, check with your network administrator or monitor the FDS help forums for advice.
\end{enumerate}



\subsubsection{Linux and Mac OS X}

A compute cluster that consists of a rack of dedicated compute nodes usually runs one of several variants of the Linux operating system. In such an environment, it is suggested, or required, that you use a job scheduler like PBS/Torque or Slurm to submit jobs by writing a short script that includes the command that launches the job, the amount of resources you require, and so on. The syntax used by PBS/Torque and Slurm is slightly different. Here is an example of a script for Intel MPI using the PBS/Torque job scheduler:
\begin{lstlisting}
#!/bin/bash
#PBS -N job_name
#PBS -e <pwd>/job_name.err
#PBS -o <pwd>/job_name.log
#PBS -l nodes=4:ppn=2
#PBS -l walltime=24:0:0
export OMP_NUM_THREADS=2
export I_MPI_PIN_DOMAIN=omp
cd <pwd>
mpiexec -n 8 <full_path>/fds job_name.fds
\end{lstlisting}
The first line invokes the bash shell. The second line provides a name for the job. The third and fourth lines provide file names for standard error and standard out. The fifth line requests 2~processors per node on 4~nodes. The sixth line requests 24~h of time. The seventh line sets the number of OpenMP threads. The eighth line is a specific Intel MPI parameter that indicates how the OpenMP threads are to be ``pinned''. The ninth line establishes the working directory. The tenth line launches FDS. You will probably have to supplement this script with additional options unique to your compute environment. Consult the man pages for {\ct mpiexec} and the chosen job scheduler for details.

If you opt to run the job without using a job scheduler, you can issue the commands directly at the command prompt:
\begin{lstlisting}
export OMP_NUM_THREADS=M
mpiexec -n N -hostfile my_hosts.txt /home/username/.../fds job_name.fds >& job_name.err &
\end{lstlisting}
The file {\ct my\_hosts.txt} looks something like this:
\begin{lstlisting}
comp1 slots=2
comp2 slots=1
comp3 slots=2
\end{lstlisting}
where {\ct compX} are the names of available nodes and {\ct slots} indicate the number of available cores on each node. The parameter {\ct slots} is optional. On a cluster shared by others, you should not run long jobs without a job scheduler because it is possible for multiple jobs to share the same nodes/cores when a scheduler is not used.
If you are using a single Linux or Mac OS X workstation, there is no need to define a host file. You just need to invoke the previously described {\ct mpiexec} line with a number of processors suitable to your case and computer. 




\section{Strategies for Running FDS}

\subsection{Using MPI and OpenMP Together}

Because it more efficiently divides the computational work, MPI is the better choice for multiple mesh simulations. However, it is possible to combine MPI and OpenMP in the same simulation. If you have multiple computers at your disposal, and each computer has multiple cores, you can assign one MPI process to each computer, and use multiple cores on each computer to speed up the processing of a given mesh using OpenMP. Typically, the use of OpenMP speeds the calculation by at most factor of 2, regardless of how many OpenMP threads you assign to each MPI process. It is usually better to divide the computational domain into more meshes and set the number of OpenMP threads to 1. This all depends on your particular OS, hardware, network traffic, and so on. You should choose a good test case and try different meshing and parallel processing strategies to see what is best for you.

\subsection{Running Very Large Jobs}

Most FDS simulations reported in the literature use one to several dozen meshes, and MPI is the method of choice to parallelize these jobs. Usually the meshes are mapped to MPI processes in a one-to-one manner and the meshes contain a comparable number of grid cells. However, it is possible to run FDS jobs that involve thousands of meshes. In 2016, the FDS developers at NIST were given access to the Oak Ridge Leadership Computing Facility at Oak Ridge National Laboratory in Tennessee. The facility provides users access to compute clusters with very large numbers of processors connected via a high speed network. FDS simulations were performed using up to approximately 10,000 MPI processes. If you have access to facilities such as this one, here are a few pointers:
\begin{enumerate}
\item Use MPI only. OpenMP will probably not speed up the run time appreciably, and it will consume cores that could be put to better use running more MPI processes.
\item For jobs using thousands of meshes/processes, add the parameter {\ct SHARED\_FILE\_SYSTEM=.FALSE.} to the {\ct MISC} line. This directs FDS to break up the Smokeview ({\ct .smv}) file according to MPI process. This will greatly speed up the preliminary part of the simulation because the Smokeview file is written serially, not in parallel. For a modest number of meshes, this serial write is not a problem, but for thousands of meshes, the initialization routines can take hours. When the job completes, you can reconstruct the Smokeview file by appending the numbered files, {\ct CHID\_n.smv}, to the main Smokeview file, {\ct CHID.smv}.
\item Set {\ct DT\_CPU} to some convenient time interval on the {\ct DUMP} line. This parameter directs FDS to periodically write out a file ({\ct CHID\_cpu.csv}) that records the wall clock time that each MPI process consumes in the major subroutines. This can help you determine if any of the MPI processes spend an inordinate amount of time idling.
\item Run your job for a short amount of time to estimate the time required for the full job. Most large compute clusters will limit you to a certain amount of wall clock time, after which your job is simply stopped. If you have to use the restart feature in FDS, practice first with a short job to make sure that the job can be continued properly.
\item Do a strong scaling study for your particular case. That is, run the job a fixed number of time steps with the least number of meshes that can fit within the machine's memory. Then divide the mesh by factors of 2, 4, or 8 until you reach a point where the increased number of meshes/processes does not provide a significant speed up.
\end{enumerate}


\section{Efficiency of Multi-Process Simulations}

At the end of a calculation, FDS prints out a file called {\ct CHID\_cpu.csv} that records the amount of CPU time that each MPI process spends in the major routines. For example, the column header {\ct VELO} stands for all the subroutines related to computing the flow velocity; {\ct MASS} stands for all the subroutines related to computing the species mass fractions and density. The column header {\ct MAIN} represents all of the CPU time that is not explicitly accounted for; that is, time spend in the main control loop. Ideally, this ought to be a few percent of the overall CPU time usage.

\subsection{MPI Efficiency}

There are two basic approaches to assessing the efficiency or {\em scalability} of MPI. The first is known as ``weak scaling,'' in which the amount of work done by each MPI process stays the same and additional processes are added to solve a larger problem. For example, if you are simulating the wind over a patch of terrain, and you keep adding more and more meshes of the same physical and numerical dimension, assigning each new mesh to its own MPI process, so as to simulate a larger and larger patch of terrain, then you would expect that the overall time of the simulation would not increase significantly with each additional mesh. The efficiency of such a calculation is given by the following expression:
\be
   E_{\rm w} = \frac{t_1}{t_N}
\ee
where $t_1$ is the CPU time for the case with 1 mesh (MPI process), and $t_N$ is the CPU time for the case with $N$ meshes (MPI processes). The left hand plot of Fig.~\ref{fig:scaling_tests} shows the results of a weak scaling study of FDS. Meshes with dimension 50 by 50 by 50 are lined up side by side, ranging from 1 to 288 meshes. Ideally, the CPU time ought to be about the same for all cases, because each MPI process is doing the same amount of work. Only mesh to mesh communication should lead to inefficiencies. However, notice in the figure that the efficiency of the 1, 2, 4, and 8 mesh cases is greater than those with more MPI processes. The reason for this is that on most compute clusters, each node has multiple cores, and typically jobs run faster when a node is less than completely full. These test cases were run at NIST, where there is a compute cluster with 8 cores per node, and one with 12 cores per node.

The second way to assess MPI efficiency is known as ``strong scaling.'' Here, you simulate a given scenario on a single mesh, and then you divide the mesh so that the cell size and the overall number of cells does not change. Ideally, if you divide a given mesh into two and run the case with two MPI processes instead of one, you would expect your computation time to decrease by a factor of two. But as you increase the number of MPI processes, you increase the amount of communication required among the processes. You also increase the overall number of boundary cells to compute, even though the overall number of gas phase cells remains the same. The efficiency of such a set of calculations is given by:
\be
   E_{\rm s} =  \frac{t_1}{N \; t_N}
\ee
In the strong study demonstrated here, a single mesh of dimension 180 by 160 by 120 is divided into a range of smaller meshes, with the smallest partitioning being 432 meshes of dimension 20 by 20 by 20. The resulting decrease in the CPU time of the entire calculation and the major subroutines is shown in the right hand plot of Fig.~\ref{fig:scaling_tests}. Ideally, the CPU time should be inversely proportional to the number of meshes (MPI processes); that is, the relative CPU times ought to follow the black dotted lines. The one notable exception to this rule is for ``COMM'' or COMMunications. This curve represents the time spent in communicating information across the network.
\begin{figure}[!ht]
\includegraphics[width=3.2in]{SCRIPT_FIGURES/weak_scaling_test}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/strong_scaling_test}
\caption[MPI scaling study]{Example of a weak (left) and strong (right) scaling study.}
\label{fig:scaling_tests}
\end{figure}

\subsubsection{OpenMP Efficiency}

To confirm the speedup provided by OpenMP, a series of test cases\footnote{The input files are available in the \href{https://github.com/firemodels/fds/tree/master/Verification/Timing_Benchmarks}{FDS GitHub repository}.} are run for two mesh sizes ($64^3$ and $128^3$), varying the number of OpenMP threads.  The setup is a simple channel flow carrying two extra species to mimic the scalar transport performed in typical fire problems. The results are shown in Fig.~\ref{fig:openmp_timing_benchmarks}.  Generally, users can expect a factor of 2 speedup using 4~cores (default setting).

\begin{figure}[ht!]
\centering
\includegraphics[width=3.2in]{SCRIPT_FIGURES/openmp_timing_benchmarks}
\caption[OpenMP timing study]{Benchmark timing comparison for the OpenMP test cases. The computer that ran these jobs has 2 (physical) sockets, and each socket has 4 (logical) cores. This explains the decrease in efficiency beyond 4 OpenMP threads.}
\label{fig:openmp_timing_benchmarks}
\end{figure}






\section{Monitoring Progress}
\label{info:monitoring_progress}

Diagnostics for a given calculation are written into a file called {\ct CHID.out}. The current simulation time and time step is written here, so you can see how far along the program has progressed. At any time during a calculation, Smokeview can be run and the progress can be checked visually.

By default, the diagnostics in the {\ct CHID.out} file are verbose.  When running large MPI jobs it may be advantageous to quiet this output, which is all written by MPI process 0.  To do this, add
\begin{lstlisting}
&DUMP SUPPRESS_DIAGNOSTICS=.TRUE. /
\end{lstlisting}
Be aware the output file will not monitor mesh boundary velocity errors in this case; it will echo only the simulation time and time step.  You could still output a {\ct BNDF} of {\ct QUANTITY='VELOCITY\_ERROR'}, if necessary.

To stop a calculation before its scheduled time, create a file in the same directory as the output files called {\ct CHID.stop}. The existence of this file stops the program gracefully, causing it to dump out the latest flow variables for viewing in Smokeview.

Since calculations can be hours or days long, there is a restart feature in FDS. Details of how to use this feature are given in Section~\ref{info:restart}. Briefly, specify at the beginning of calculation how often a ``restart'' file should be saved. Should something happen to disrupt the calculation, like a power outage, the calculation can be restarted from the time the last restart file was saved.

It is also possible to control the stop time and the dumping of restart files by using control functions as described in Section~\ref{info:CTRL}.




\chapter{User Support}

It is not unusual over the course of a project to run into various problems, some related to FDS, some related to your computer. FDS is an CPU and memory intensive calculation that can push your computer's processor and memory to its limits. In fact, there are no hardwired bounds within FDS that prevent you from starting a calculation that is too large for your hardware. Even if your machine has adequate memory (RAM), you can still easily set up calculations that can require weeks or months to complete. It is difficult to predict at the start of a simulation just how long and how much memory will be required. Learn how to monitor the resource usage of your computer. Start with small calculations and build your way up.

Although many features in FDS are fairly mature, there are many that are not. FDS is used for practical engineering applications, but also for research in fire and combustion. As you become more familiar with the software, you will inevitably run into areas that are of current research interest. Indeed, burning a roomful of ordinary furniture is one of the most challenging applications of the model. So be patient, and learn to dissect a given scenario into its constitutive parts. For example, do not attempt to simulate a fire spreading through an entire floor of a building unless you have simulated the burning of the various combustibles with relatively small calculations.

Along with the FDS User's Guide, there are resources available on the Internet. These resources include an ``Issue Tracker'' for reporting bugs and requesting new features, a ``Discussion Group'' for clarifying questions and discussing more general topics rather than just specific problems, and ``Wiki Pages'' that provide supplementary information about FDS-SMV development, third-party tools, and other resources. Before using these on-line resources, it is important to first try to solve your own problems by performing simple test calculations or debugging your input file. The next few sections provide a list of error statements and suggestions on how to solve problems.


\section{The Version Number}

If you encounter problems with FDS, it is crucial that you submit, along with a description of the problem, the FDS version number. Each release of FDS comes with a version number, for example 6.7.2, where the first number is the {\em major} release, the second is the {\em minor} release, and the third is the {\em maintenance} release. Major releases occur every few years, and as the name implies significantly change the functionality of the model. Minor releases occur every few months, and may cause minor changes in functionality. Release notes can help you decide whether the changes should affect the type of applications that you typically do. Maintenance releases are just bug fixes, and should not affect code functionality. To get the version number, just type the executable at the command prompt without an input file, and the relevant information will appear, along with a date of compilation (useful to you) and a so-called Git hash tag (useful to us).  The Git hash tag refers to the GitHub repository number of the source code. It allows us to go back in time and recover the exact source code files that were used to build that executable.

Get in the habit of checking the version number of your executable, periodically checking for new releases which might already have addressed your problem, and telling us what version you are using if you report a problem.





\section{Common Error Statements}
\label{info:Errors}

An FDS calculation may end before the specified time limit. Following is a list of common error statements and how to diagnose the problems:
\begin{description}
\item[{\bf Input File Errors}:] The most common errors in FDS are due to mis-typed input statements. These errors result in the immediate halting of the program and a statement like, ``ERROR: Problem with the HEAD line.'' For these errors, check the line in the input file named in the error statement. Make sure the parameter names are spelled correctly. Make sure that a / (forward slash) is put at the end of each namelist entry. Make sure that the right type of information is being provided for each parameter, like whether one real number is expected, or several integers, or whatever. Make sure there are no non-ASCII characters being used, as can sometimes happen when text is cut and pasted from other applications or word-processing software. Make sure zeros are zeros and O's are O's. Make sure 1's are not !'s. Make sure apostrophes are used to designate character strings. Make sure the text file on a Unix/Linux machine was not created on a Windows machine, and {\em vice versa}. Make sure that all the parameters listed are still being used -- new versions of FDS often drop or change parameters forcing you to re-examine old input files.
\item [{\bf Numerical Instability Errors}:] It is possible that during an FDS calculation the flow velocity at some location in the domain can increase due to numerical error causing the time step size to decrease to a point\footnote{By default, the calculation is stopped when the time step drops below 0.0001 of the initial time step. This factor can be changed via the {\ct TIME} line by specifying the {\ct LIMITING\_DT\_RATIO}.} where logic in the code decides that the results are unphysical and stops the calculation with an error message in the file {\ct CHID.out}. In these cases, FDS ends by dumping out one final Plot3D file giving you a hint as to where the error is occurring within the computational domain. Usually, a numerical instability can be identified by fictitiously large velocity vectors emanating from a small region within the domain. Common causes of such instabilities are:
    \begin{itemize}
    \item mesh cells that have an aspect ratio larger than 2 to 1
    \item high speed flow through a small opening
    \item a sudden change in the heat release rate
    \item the removal or creation of an obstruction, like the opening or closing of a door
    \item a high (>100 g/mol) molecular weight fuel molecule that is not in the FDS database, Table~\ref{tab:gasspecies}. In such cases, reduce the molecular weight but maintain the atom ratios.
    \item long, sealed tunnels, in which pressure fluctuations can cause spurious numerical artifacts. See Section~\ref{info:PRES} for details.
    \end{itemize}
    There are various ways to solve the problem, depending on the situation. Try to diagnose and fix the problem before reporting it. It is difficult for anyone but the originator of the input file to diagnose the problem.
\item[{\bf Inadequate Computer Resources}:] The calculation might be using more RAM than the machine has (you will see an error message like ``ERROR: Memory allocation failed for ZZ in the routine INIT'') , or the output files could have used up all the available disk space. In these situations, the computer may or may not produce an intelligible error message. Sometimes the computer is just unresponsive. It is your responsibility to ensure that the computer has adequate resources to do the calculation. Remember, there is no limit to how big or how long FDS calculations can be -- it depends on the resources of the computer. For any new simulation, try running the case with a modest-sized mesh, and gradually make refinements until the computer can no longer handle it. Then back off somewhat on the size of the calculation so that the computer can comfortably run the case. Trying to run with 90~\% to 100~\% of computer resources is risky; using MPI and mulitple machines would be better. If you are using a Linux/Unix machine, make sure that the stacksize is unlimited, which will allow FDS to access as much of the RAM as possible. Changing the stacksize limit differs with each shell type, so it is best to do an on-line search to find out how to ensure that your stacksize is unlimited.
\item[{\bf Run-Time Errors}:] An error occurs either within the computer operating system or the FDS program. An error message is printed out by the operating system of the computer onto the screen or into the diagnostic output file. This message is most often unintelligible to most people, including the programmers, although occasionally one might get a small clue if there is mention of a specific problem, like ``stack overflow,'' ``divide by zero,'' or ``file write error, unit=...'' Sometimes the error message simply refers to a ``Segmentation Fault.'' These errors may be caused by a bug in FDS, for example if a number is divided by zero, or an array is used before it is allocated, or any number of other problems. Before reporting the error to the Issue Tracker, try to systematically simplify the input file until the error goes away. This process usually brings to light some feature of the calculation responsible for the problem and helps in the debugging.
\item[{\bf File Writing Errors}:] Occasionally, especially on Windows machines, FDS fails because it is not permitted to write to a file. A typical error statement reads:
\begin{lstlisting}
forrtl: severe (47): write to READONLY file, unit 8598, file C:\Users\...\
\end{lstlisting}
 The unit, in this case 8598, is just a number that FDS has associated with one of the output files. If this error occurs just after the start of the calculation, you can try adding the phrase \\ {\ct FLUSH\_FILE\_BUFFERS=.FALSE.} \\ on the {\ct DUMP} line of the input file (see Section~\ref{info:DUMP}). This will prevent FDS from attempting to flush the contents of the internal buffers, something it does to make it possible to view the FDS output in Smokeview during the FDS simulation. On some Windows machines, you might encounter security settings that prevent command line programs such as FDS from writing to system folders that contain program files. In this case, try to rerun the case in a non-system folder (i.e., a location within your home directory).
\item[{\bf Poisson Initialization}:] Sometimes at the very start of a calculation, an error appears stating that there is a problem with the ``Poisson initialization.'' The equation for pressure in FDS is known as the Poisson equation. The Poisson solver consists of large system of linear equations that must be initialized at the start of the calculation. Most often, an error in the initialization step is due to a mesh {\ct IJK} dimension being less than 4 (except in the case of a two-dimensional calculation). It is also possible that something is fundamentally wrong with the coordinates of the computational domain. Diagnose the problem by checking the {\ct MESH} lines in the input file.
\end{description}


\section{Support Requests and Bug Tracking}

Because FDS development is on-going, problems will inevitably occur with various routines and features. The developers need to know if a certain feature is not working, and reporting problems is encouraged. However, the problem must be clearly identified. The best way to do this is to simplify the input file as much as possible so that the bug can be diagnosed (i.e., create and submit a minimal working example). Also, limit the bug reports to those features that clearly do not work. Physical problems such as fires that do not ignite, flames that do not spread, etc., may be related to the mesh resolution or scenario formulation, and you need to investigate the problem first before reporting it. If an error message originates from the operating system as opposed to FDS, first investigate some of the more obvious possibilities, such as memory size, disk space, etc.

If that does not solve the problem, report the problem with as much information about the error message and circumstances related to the problem. The input file should be simplified as much as possible so that the bug occurs early in the calculation. Attach the simplified input file if necessary, following the instructions provided at the web site. In this way, the developers can quickly run the problematic input file and hopefully diagnose the problem.

Note: Reports of specific bugs, problems, feature requests, and enhancements should be posted to the Issue Tracker and not the Discussion Group.






\part{Writing an FDS Input File}
\label{info:inputfilecreation}



\chapter{The Basic Structure of an Input File}
\label{info:fdsBasic}


\section{Naming the Input File}

The operation of FDS is based on a single ASCII\footnote{ASCII -- American Standard Code
for Information Interchange. There are 256 characters that make up the standard ASCII text.} text file containing parameters organized into
{\em namelist}\footnote{A {\em namelist} is a Fortran input record.} groups.
The input file provides FDS  with all of the necessary information to
describe the scenario.
The input file is saved with a name such as {\ct job\_name.fds},
where {\ct job\_name} is any character string that helps to identify
the simulation. If this same string is repeated under the {\ct HEAD} namelist group within the
input file, then all of the output files associated with the calculation will then have this common prefix name.

There should be no blank spaces in the job name. Instead use the underscore
character to represent a space.  Using an underscore characters instead of a space also applies
to the general practice of naming directories on your system.

Be aware that FDS will simply over-write the output files of a given case if its assigned
name is the same. This is convenient when developing an input file because you save on disk space. Just be careful
not to overwrite a calculation that you want to keep.



\section{Namelist Formatting}

Parameters are specified within the input file by using {\em namelist} formatted records. Each namelist record begins with the ampersand character, {\ct \&}, followed immediately by the name of the namelist group, then a comma-delimited list of the input parameters, and finally a forward slash, {\ct /}. For example, the line
\begin{lstlisting}
&DUMP NFRAMES=1800, DT_HRR=10., DT_DEVC=10., DT_PROF=30. /
\end{lstlisting}
sets various values of parameters contained in the {\ct DUMP} namelist group. The meanings of these various parameters will be explained in subsequent chapters. The namelist records can span multiple lines in the input file, but just be sure to end the record with a slash or else the data will not be understood. Do not add anything to a namelist line other than the parameters and values appropriate for that group. Otherwise, FDS will stop immediately upon execution.

Parameters within a namelist record can be separated by either commas, spaces, or line breaks. It is recommended that you use commas or line breaks, and never use tab stops because they are not explicitly defined in the namelist data structure. Comments and notes can be written into the file so long as nothing comes before the ampersand except a space and nothing comes between the ampersand and the slash except appropriate parameters corresponding to that particular namelist group.

The parameters in the input file can be integers, reals, character strings, or logical parameters. A logical parameter is either {\ct .TRUE.} or {\ct .FALSE.} -- the periods are a Fortran convention. Character strings that are listed in this User's Guide must be copied exactly as written -- the code is case sensitive and underscores {\em do} matter. The maximum length of most character input parameters is 60.

Most of the input parameters are simply real or integer scalars, like {\ct DT=0.02}, but sometimes the inputs are
multidimensional arrays. For example, when describing a particular solid surface, you need to express the mass fractions of multiple materials that are to be found in multiple layers. The input array {\ct MATL\_MASS\_FRACTION(IL,IC)} is intended to convey to FDS the mass fraction of component {\ct IC} of layer {\ct IL}. For example, if the mass fraction of the second material of the third layer is 0.5, then write
\begin{lstlisting}
MATL_MASS_FRACTION(3,2)=0.5
\end{lstlisting}
To enter more than one mass fraction, use this notation:
\begin{lstlisting}
MATL_MASS_FRACTION(1,1:3)=0.5,0.4,0.1
\end{lstlisting}
which means that the first three materials of layer 1 have mass fractions of 0.5, 0.4, and 0.1, respectively. The notation {\ct 1:3} means array elements 1 through 3, inclusive.

Note that character strings can be enclosed either by single or double quotation marks. Be careful not to create the input file by pasting text from something other than a simple text editor, in which case the punctuation marks may not transfer properly into the text file.

Some text file encodings may not work on all systems. If file reading errors occur and no typographical errors can be found in the input file, try saving the input file using a different encoding. For example, the text file editor Notepad works fine on a Windows PC, but a file edited in Notepad may not work on Linux or Mac OS~X because of the difference in line endings between Windows and Unix/Linux operating systems. The editor Wordpad typically works better, but try a simple case first.


\section{Input File Structure}

In general, the namelist records can be entered in any order in the input file, but it is a good idea to organize them
in some systematic way. Typically, general information is listed near the top of the input file, and detailed information, like
obstructions, devices, and so on, are listed below. FDS scans the entire input file each time it processes a particular namelist group.
With some text editors, it has been noticed that the last line of the file is often not read by FDS because of the presence of an
``end of file'' character.
To ensure that FDS reads the entire input file, add
\begin{lstlisting}
&TAIL /
\end{lstlisting}
as the last line at the end of the input file. This completes the file from {\ct \&HEAD} to {\ct \&TAIL}. FDS does not even look for
this last line. It just forces the ``end of file'' character past relevant input.

Another general rule of thumb when writing input files is to only add parameters that make a change from the
default value. That way, you can more easily distinguish between what you want and what FDS wants.
Add comments liberally to the file, so long as
these comments do not fall within the namelist records.

The general structure of an input file is shown below, with many
lines of the original validation input file\footnote{The actual input file, WTC\_05.fds, is part of the FDS
Validation Suite} removed for clarity.

\begin{lstlisting}
&HEAD CHID='WTC_05', TITLE='WTC Phase 1, Test 5' /
&MESH IJK=90,36,38, XB=-1.0,8.0,-1.8,1.8,0.0,3.82 /
&TIME T_END=5400. /
&MISC TMPA=20. /
&DUMP NFRAMES=1800, DT_HRR=10., DT_DEVC=10., DT_PROF=30. /

&REAC FUEL       = 'N-HEPTANE'
      FYI        = 'Heptane, C_7 H_16'
      C          = 7.
      H          = 16.
      CO_YIELD   = 0.008
      SOOT_YIELD = 0.015 /

&OBST XB= 3.5, 4.5,-1.0, 1.0, 0.0, 0.0, SURF_ID='STEEL FLANGE' /  Fire Pan
...
&SURF ID        = 'STEEL FLANGE'
      COLOR     = 'BLACK'
      MATL_ID   = 'STEEL'
      BACKING   = 'EXPOSED'
      THICKNESS = 0.0063 /
...
&VENT MB='XMIN', SURF_ID='OPEN' /
...
&SLCF PBY=0.0, QUANTITY='TEMPERATURE', VECTOR=.TRUE. /
...
&BNDF QUANTITY='GAUGE HEAT FLUX' /
...
&DEVC XYZ=6.04,0.28,3.65, QUANTITY='VOLUME FRACTION', SPEC_ID='OXYGEN', ID='EO2_FDS' /
...
&TAIL / End of file.
\end{lstlisting}
It is recommended that when looking at a new scenario, first select a pre-written input file that resembles the case, make the necessary changes, then run the case at fairly low mesh resolution to determine if the geometry is set up correctly. It is best to start off with a relatively simple file that captures the main features of the problem without getting tied down with too much detail that might mask a fundamental flaw in the calculation. Initial calculations ought to be meshed coarsely so that the run times are less than an hour and corrections can easily be made without wasting too much time. As you learn how to write input files, you will continually run and re-run your case as you add in complexity.

Table~\ref{tbl:namelistgroups} provides a quick reference to all the namelist parameters and where you can find the reference to where it is introduced in the document and the table containing all of the keywords for each group.

\vspace{\baselineskip}
\begin{table}[ht]
\begin{center}
\caption{Namelist Group Reference Table}
\label{tbl:namelistgroups}
\begin{tabular}{|c|l|c|c|}
\hline
Group Name  & Namelist Group Description   & Reference Section & Parameter Table  \\ \hline
{\ct BNDF}  & Boundary File Output         & \ref{info:BNDF} & \ref{tbl:BNDF}  \\ \hline
{\ct CATF}  & Concatenate Input Files      & \ref{info:CATF} & \ref{tbl:CATF}  \\ \hline
{\ct CLIP}  & Clipping Parameters          & \ref{info:CLIP} & \ref{tbl:CLIP}  \\ \hline
{\ct COMB}  & Combustion Parameters        & \ref{info:COMB} & \ref{tbl:COMB}  \\ \hline
{\ct CSVF}  & Velocity Input File          & \ref{info:CSVF} & \ref{tbl:CSVF}  \\ \hline
{\ct CTRL}  & Control Function Parameters  & \ref{info:CTRL} & \ref{tbl:CTRL}  \\ \hline
{\ct DEVC}  & Device Parameters            & \ref{info:DEVC} & \ref{tbl:DEVC}  \\ \hline
{\ct DUMP}  & Output Parameters            & \ref{info:DUMP} & \ref{tbl:DUMP}  \\ \hline
{\ct HEAD}  & Input File Header            & \ref{info:HEAD} & \ref{tbl:HEAD}  \\ \hline
{\ct HOLE}  & Obstruction Cutout           & \ref{info:HOLE} & \ref{tbl:HOLE}  \\ \hline
{\ct HVAC}  & Heating, Vent., Air Cond.    & \ref{info:HVAC} & \ref{tbl:HVAC}  \\ \hline
{\ct INIT}  & Initial Condition            & \ref{info:INIT} & \ref{tbl:INIT}  \\ \hline
{\ct ISOF}  & Isosurface File Output       & \ref{info:ISOF} & \ref{tbl:ISOF}  \\ \hline
{\ct MATL}  & Material Property            & \ref{info:MATL} & \ref{tbl:MATL}  \\ \hline
{\ct MESH}  & Mesh Parameters              & \ref{info:MESH} & \ref{tbl:MESH}  \\ \hline
{\ct MISC}  & Miscellaneous                & \ref{info:MISC} & \ref{tbl:MISC}  \\ \hline
{\ct MOVE}  & Transformation Parameters    & \ref{info:MOVE} & \ref{tbl:MOVE}  \\ \hline
{\ct MULT}  & Multiplier Parameters        & \ref{info:MULT} & \ref{tbl:MULT}  \\ \hline
{\ct OBST}  & Obstruction                  & \ref{info:OBST} & \ref{tbl:OBST}  \\ \hline
{\ct PART}  & Lagrangian Particle          & \ref{info:PART} & \ref{tbl:PART}  \\ \hline
{\ct PRES}  & Pressure Solver Parameters   & \ref{info:PRES} & \ref{tbl:PRES}  \\ \hline
{\ct PROF}  & Profile Output               & \ref{info:PROF} & \ref{tbl:PROF}  \\ \hline
{\ct PROP}  & Device Property              & \ref{info:PROP} & \ref{tbl:PROP}  \\ \hline
{\ct RADF}  & Radiation Output File        & \ref{info:RADF} & \ref{tbl:RADF}  \\ \hline
{\ct RADI}  & Radiation                    & \ref{info:RADI} & \ref{tbl:RADI}  \\ \hline
{\ct RAMP}  & Ramp Profile                 & \ref{info:RAMP} & \ref{tbl:RAMP}  \\ \hline
{\ct REAC}  & Reaction Parameters          & \ref{info:REAC} & \ref{tbl:REAC}  \\ \hline
{\ct SLCF}  & Slice File Output            & \ref{info:SLCF} & \ref{tbl:SLCF}  \\ \hline
{\ct SPEC}  & Species Parameters           & \ref{info:SPEC} & \ref{tbl:SPEC}  \\ \hline
{\ct SURF}  & Surface Properties           & \ref{info:SURF} & \ref{tbl:SURF}  \\ \hline
{\ct TABL}  & Tabulated Particle Data      & \ref{info:TABL} & \ref{tbl:TABL}  \\ \hline
{\ct TIME}  & Simulation Time              & \ref{info:TIME} & \ref{tbl:TIME}  \\ \hline
{\ct TRNX}  & Mesh Stretching              & \ref{info:TRNX} & \ref{tbl:TRNX}  \\ \hline
{\ct VENT}  & Vent Parameters              & \ref{info:VENT} & \ref{tbl:VENT}  \\ \hline
{\ct WIND}  & Wind Parameters              & \ref{info:WIND} & \ref{tbl:WIND}  \\ \hline
{\ct ZONE}  & Pressure Zone Parameters     & \ref{info:ZONE} & \ref{tbl:ZONE}  \\ \hline
\end{tabular}
\end{center}
\end{table}


\section{Concatenating input files}
\label{info:CATF}

The namelist group {\ct \&CATF} allows for the inclusion of input information from different files into a simulation. Consider an FDS input file {\ct couch2.fds}\footnote{Referenced files can be found in the {\ct Examples/Fires} directory of the FDS bundle.} which contains
\begin{lstlisting}
&HEAD CHID='couch2', TITLE='Single Couch Test Case using two meshes & CATF files.'  /
&MESH IJK=12,10,24, XB=1.1,2.3,3.6,4.6,0.0,2.4, MULT_ID='mesh' /
&MULT ID='mesh', DX=1.2, I_UPPER=1 /
&TIME T_END=600. /
...
&CATF OTHER_FILES='upholstery_matl.tpl','gypsum_walls.tpl' / #Upholstery & gypsum.

# Couch OBSTS:
&OBST XB= 1.50, 3.10, 3.80, 4.60, 0.00, 0.40 /
&OBST XB= 1.50, 3.10, 3.80, 4.60, 0.40, 0.60, SURF_ID='UPHOLSTERY', BULK_DENSITY=... /
&OBST XB= 1.30, 1.50, 3.80, 4.60, 0.00, 0.90, SURF_ID='UPHOLSTERY', BULK_DENSITY=... /
&OBST XB= 3.10, 3.30, 3.80, 4.60, 0.00, 0.90, SURF_ID='UPHOLSTERY', BULK_DENSITY=... /
&OBST XB= 1.50, 3.10, 4.40, 4.60, 0.60, 1.20, SURF_ID='UPHOLSTERY', BULK_DENSITY=... /

&CATF OTHER_FILES='couch2_devices.dat' / # Devices generated by script.
...
&TAIL/
\end{lstlisting}
%
We note that the {\ct \&CATF} group is defined in two lines. In the first line, two files {\ct upholstery\_matl.tpl}, {\ct gypsum\_walls.tpl} are defined on
the namelist {\ct OTHER\_FILES} field. These contain information in the form of templates, on a typical upholstery material for the couch, and gypsum wall defined for the back wall and roof of the case. Up to 20 files can be listed in one {\ct \&CATF} line. For example, for the gypsum wall template, the material and surface information is provided in FDS input format as:
%
\begin{lstlisting}
&MATL ID            = 'GYPSUM PLASTER'
      FYI           = 'Quintiere, Fire Behavior'
      CONDUCTIVITY  = 0.48
      SPECIFIC_HEAT = 0.84
      DENSITY       = 1440. /

&SURF ID             = 'WALL'
      DEFAULT        = .TRUE.
      RGB            = 200,200,200
      MATL_ID        = 'GYPSUM PLASTER'
      THICKNESS      = 0.012 /
\end{lstlisting}
In the second {\ct \&CATF} line, a file {\ct couch2\_devices.dat} defines in FDS input format a set of sensor device lines, potentially produced by an
automated script.

When FDS is invoked with the {\ct couch2.fds} input file, it will concatenate the input contents of this file and all files defined in its {\ct \&CATF} lines,
into a simulation input file called {\ct couch2\_cat.fds} (here {\ct CHID='couch2'} is the case ID in the original {\ct couch2.fds} input file).
Then FDS will proceed to run the case defined by the concatenated input file generated.


\chapter{Setting the Bounds of Time and Space}

This chapter describes global input parameters that affect the general scope of the simulation, like
the simulation time and the size and extent of the computational domain. Essentially, these parameters
establish the spatial and temporal coordinate systems that are used by all other components of the simulation, which is
why these parameters are usually listed at the top of the input file and why they are described here first.


\section{Naming the Job: The \texorpdfstring{{\tt HEAD}}{HEAD} Namelist Group (Table \ref{tbl:HEAD})}
\label{info:HEAD}

The first thing to do when setting up an input file is to give the
job a name.  The name of the job is important because often a project
involves numerous simulations in which case the names of the individual
simulations should be meaningful and help to organize the project.  The namelist group {\ct HEAD} contains
two parameters, as in this example:
\begin{lstlisting}
&HEAD CHID='WTC_05', TITLE='WTC Phase 1, Test 5' /
\end{lstlisting}
\begin{description}
\item {\ct CHID} stands for \emph{Character ID}, it is a string of 40 characters or less used to tag the output files. If, for example, {\ct CHID='WTC\_05'}, it is convenient to name the input data file {\ct WTC\_05.fds} so that the input file can be associated with the output files. No periods or spaces are allowed in {\ct CHID} because the output files are tagged with suffixes that are meaningful to certain computer operating systems.  If {\ct CHID} is not specified, then it will be set to the name of the input file minus everything at and beyond the first period.
\item {\ct TITLE} is a string of 256 characters or less that describes the simulation. It is simply a descriptive text that is passed to various output files.
\end{description}


\section{Simulation Time: The \texorpdfstring{{\tt TIME}}{TIME} Namelist Group (Table \ref{tbl:TIME})}
\label{info:TIME}

{\ct TIME} is the name of a group of parameters that define the time
duration of the simulation and the initial time step used to advance
the solution of the discretized equations.

\subsection{Basics}
\label{info:TIME_Basics}

Usually, only the duration of the simulation is required on this line, via the parameter {\ct T\_END}. The default is 1~s. For example, the following line will instruct FDS to run the simulation for 5400~s.
\begin{lstlisting}
&TIME T_END=5400. /
\end{lstlisting}
If {\ct T\_END} is set to zero, only the set-up work is performed, allowing you to quickly check the geometry in Smokeview.

If you want the time line to start at a number other than zero, you can use the parameter {\ct T\_BEGIN} to specify the time written to file for the first time step. This would be useful for matching time lines of experimental data or video recordings.

Time-based {\ct RAMP}s are evaluated using the actual time if the {\ct RAMP} activation time is the same as {\ct T\_BEGIN}; otherwise, they are evaluated using the time from when the {\ct RAMP} activates.  Therefore, if you are setting {\ct T\_BEGIN} in order to test a time-based {\ct CTRL} or {\ct DEVC} that is ultimately linked to a {\ct RAMP}, then you should set {\ct T\_BEGIN} to be slightly less than the time the {\ct RAMP} will activate. For example if you are testing a {\ct VENT} that is to open at 10~s whose {\ct SURF\_ID} uses a {\ct RAMP}, {\ct T\_BEGIN} should be set slightly less than 10~s.


\subsection{Special Topic: Controlling the Time Step}
\label{info:TIME_Control}

The initial time step size can be specified with {\ct DT}. This parameter is normally set automatically by dividing the size of a mesh cell by the characteristic velocity of the flow. During the calculation, the time step is adjusted so that the CFL (Courant, Friedrichs, Lewy) condition is satisfied. The default value of {\ct DT} is $5 \, (\dx \, \dy \, \dz)^\ot/\sqrt{gH}$ s, where $\dx$, $\dy$, and $\dz$ are the dimensions of the smallest mesh cell, $H$ is the height of the computational domain, and $g$ is the acceleration of gravity. Note that by default the time step is never allowed to increase above its initial value. To allow this to happen, set {\ct RESTRICT\_TIME\_STEP=.FALSE.}

If something sudden is to happen right at the start of a simulation, like a sprinkler activation, it is a good idea to set the initial time step to avoid a numerical instability caused by too large a time step. Experiment with different values of {\ct DT} by monitoring the initial time step sizes recorded in the output file {\ct job\_name.out}.

At the end of the first part of the explicit predictor-corrector time update, the time step is checked to ensure that it is within the appropriate stability bounds. If it is not, it is adjusted up or down by 10~\% (or until it is within limits) and the predictor part of the time step is re-run. If you want to prevent FDS from automatically changing the time step, set {\ct LOCK\_TIME\_STEP} equal to {\ct .TRUE.} on the {\ct TIME} line, in which case the specified time step, {\ct DT}, will not be adjusted. This parameter is intended for diagnostic purposes only, for example, timing program execution. It can lead to numerical instabilities if the initial time step is set too high.

The diagnostic output file called {\ct CHID.out} contains information about the time step and CFL number in each mesh. However, for simulations that involve dozens or hundreds of meshes, it can be difficult to assess the global time step information. For detailed information about the time step, there is an optional output file called {\ct CHID\_cfl.csv} that contains the time, time step, maximum CFL number, maximum VN (Von Neumann) number, the mesh and mesh indices where these maximum values occur, and the six velocity components on the six faces of the grid cell where the maximum CFL number occurs. To output this file, set {\ct CFL\_FILE} to {\ct .TRUE.} on the {\ct DUMP} line. It is normally set to {\ct .FALSE.}


\subsection{Special Topic: Steady-State Applications}
\label{info:steady_state}

Occasionally, there are applications in which only the steady-state solution (in a time-averaged sense) is desired. However, the time necessary to
heat the walls to steady-state can make the cost of the calculation prohibitive. In these situations, if you specify a
{\ct TIME\_SHRINK\_FACTOR} of, say, 10, the specific heats of the various materials is reduced by a factor of 10, speeding up the heating
of these materials roughly by 10. An example of an application where this parameter is handy is a validation experiment where a steady heat source
warms up a compartment to a nearly equilibrium state at which point time-averaged flow quantities are measured.

Note that when {\ct TIME\_SHRINK\_FACTOR} is used a device with {\ct QUANTITY='TIME'} or a device or control function with a {\ct DELAY} will have those values adjusted by the value of {\ct TIME\_SHRINK\_FACTOR}.  For example if a 10~s {\ct DELAY} is specified for a {\ct CTRL} input with a {\ct TIME\_SHRINK\_FACTOR} of 10, then FDS will adjust the {\ct DELAY} to 1~s.

\newpage

\section{Computational Meshes: The \texorpdfstring{{\tt MESH}}{MESH} Namelist Group (Table \ref{tbl:MESH})}
\label{info:MESH}

All FDS calculations must be performed within a domain that is made up of rectilinear volumes called {\em meshes}. Each mesh is divided into rectangular {\em cells}, the number of which depends on the desired resolution of the flow dynamics. {\ct MESH} is the namelist group that defines the computational domain.

\subsection{Basics}
\label{info:MESH_Basics}

A mesh is a single right parallelepiped, i.e., a box. The coordinate system within a mesh conforms to the right hand rule. The origin point of a mesh is defined by the first, third and fifth values of the real number sextuplet, {\ct XB}, and the opposite corner is defined by the second, fourth and sixth values. For example,
\begin{lstlisting}
&MESH IJK=10,20,30, XB=0.0,1.0,0.0,2.0,0.0,3.0 /
\end{lstlisting}
defines a mesh that spans the volume starting at the origin and extending 1~m in the positive $x$ direction, 2~m in the positive $y$ direction, and 3~m in the positive $z$ direction. The mesh is subdivided into uniform cells via the parameter {\ct IJK}. In this example, the mesh is divided into 10~cm cubes. It is best if the mesh cells resemble cubes; that is, the length, width and height of the cells ought to be roughly the same. If it is desired that the mesh cells in a particular direction not be uniform in size, then the namelist groups {\ct TRNX}, {\ct TRNY} and/or {\ct TRNZ} may be used to alter the uniformity of the mesh (See Section~\ref{info:TRNX}).

Any obstructions or vents that extend beyond the boundary of the mesh are cut off at the boundary. There is no penalty for defining objects outside of the mesh, and these objects will not appear in Smokeview.

The pressure solver in FDS employs Fast Fourier Transforms (FFTs) in the $y$ and $z$ directions, and this algorithm works most efficiently if the number of cells in these directions (the {\ct J} and {\ct K} of {\ct IJK}) can be factored into low primes, like 2, 3, and 5. The number of cells in the $x$ direction (the {\ct I} in {\ct IJK}) is not affected by this restriction because the pressure solver does not use an FFT in the $x$ direction. However, since the pressure solver uses less than 10~\% of the total CPU time, the gains in using low prime dimensions are usually negligible. Experiment with different mesh dimensions to ensure that those that are ultimately used do not unduly slow down the calculation.



\subsection{Two-Dimensional and Axially-Symmetric Calculations}
\label{info:2D}

The governing equations solved in FDS are written in terms of a three dimensional Cartesian coordinate system. However, a two dimensional Cartesian or two dimensional cylindrical (axially-symmetric) calculation can be performed by setting the {\ct J} in the {\ct IJK} triplet to 1 on the {\ct MESH} line. For axial symmetry, add {\ct CYLINDRICAL=.TRUE.} to the {\ct MESH} line, and the coordinate $x$ is then interpreted as the radial coordinate $r$. No boundary conditions should be set at the planes $y=\hbox{\ct YMIN=XB(3)}$ or $y=\hbox{\ct YMAX=XB(4)}$, nor at $r=\hbox{\ct XMIN=XB(1)}$ in an axially-symmetric calculation in which $r=\hbox{\ct XB(1)=0}$. For better visualizations, the difference between {\ct XB(4)} and {\ct XB(3)} should be small so that the Smokeview rendering appears to be in 2-D. An example of an axially-symmetric helium plume is given in Section~\ref{baroclinic_torque}.


\subsection{Multiple Meshes}
\label{info:multimesh}

\begin{figure}[ht!]
\includegraphics[width=\textwidth]{FIGURES/hallways}
\caption{An example of a multiple-mesh geometry.}
\label{fig:domain}
\end{figure}

The term ``multiple meshes'' means that the computational domain consists of more than one computational mesh, usually connected although this is not required. If more than one mesh is used, there should be a {\ct MESH} line for each. The order in which these lines are entered in the input file matters. In general, the meshes should be entered from finest to coarsest. FDS assumes that a mesh listed first in the input file has precedence over a mesh listed second if the two meshes overlap. Meshes can overlap, abut, or not touch at all. In the last case, essentially two separate calculations are performed with no communication at all between them. Obstructions and vents are entered in terms of the overall coordinate system and need not apply to any one particular mesh. Each mesh checks the coordinates of all the geometric entities and decides whether or not they are to be included.

To run FDS in parallel using MPI (Message Passing Interface), you {\bf must} break up the computational domain into multiple meshes so that the workload can be divided among the computers. In general, it is better to run multiple mesh cases using MPI if you have the computers available, but be aware that two computers will not necessarily finish the job in half the time as one. For MPI to work well, there has to be a comparable number of cells assigned to each MPI process, or otherwise most of the processes will sit idle waiting for the one with the largest number of cells to finish processing each time step. You can use multiple meshes on a single processor without using MPI , in which case one CPU will serially process each mesh, one by one.

Usually in a MPI calculation, each mesh is assigned its own process, and each process its own processor. However, it is possible to assign more than one mesh to a single process, and it is possible to assign more than one process to a single processor. Consider a case that involves six meshes:
\begin{lstlisting}
&MESH ID='mesh1', IJK=..., XB=..., MPI_PROCESS=0 /
&MESH ID='mesh2', IJK=..., XB=..., MPI_PROCESS=1 /
&MESH ID='mesh3', IJK=..., XB=..., MPI_PROCESS=1 /
&MESH ID='mesh4', IJK=..., XB=..., MPI_PROCESS=2 /
&MESH ID='mesh5', IJK=..., XB=..., MPI_PROCESS=3 /
&MESH ID='mesh6', IJK=..., XB=..., MPI_PROCESS=3 /
\end{lstlisting}
The parameter {\ct MPI\_PROCESS} instructs FDS to assign that particular mesh to the given process. In this case, only four processes are to be started, numbered 0 through 3. Note that the processes need to be invoked in ascending order, starting with 0. Why would you do this? Suppose you only have four processors available for this job. By starting only four processes instead of six, you can save time because `mesh2' and `mesh3' can communicate directly with each other without having to transmit data using MPI calls over the network. Same goes for `mesh5' and `mesh6'. In essence, it is as if these mesh pairs are neighbors and need not send mail to each other via the postal system. The letters can just be walked next door.

Additionally to the mesh assignment to individual MPI processes, the number of OpenMP threads for each MPI process may be specified. The parameter {\ct N\_THREADS} instructs FDS to set this number of threads and must be consistent for all meshes on the same MPI process, but may vary between them:
\begin{lstlisting}
&MESH ID='mesh1', IJK=..., XB=..., MPI_PROCESS=0 /
&MESH ID='mesh2', IJK=..., XB=..., MPI_PROCESS=1, N_THREADS=2 /
&MESH ID='mesh3', IJK=..., XB=..., MPI_PROCESS=1, N_THREADS=2 /
&MESH ID='mesh4', IJK=..., XB=..., MPI_PROCESS=2, N_THREADS=4 /
&MESH ID='mesh5', IJK=..., XB=..., MPI_PROCESS=3 /
&MESH ID='mesh6', IJK=..., XB=..., MPI_PROCESS=3 /
\end{lstlisting}
Notes: An unspecified value will result in the default number of threads (see \ref{single_mesh}) on the MPI process. Some cluster systems do not support a heterogeneous distribution of resources, here computational cores, per MPI process. Therefore, the number of OpenMP threads may change, but not the amount of cores assigned to the MPI process.

For cases involving many meshes, you might want to assign them colors using either the character string {\ct COLOR} or the integer triplet {\ct RGB}. You may also want to consider using the multiplying feature to easily create a 3-D array of meshes. See Section~\ref{info:MULT} for details.

Some parallel computing environments do not have a centralized file system, in which case FDS must write the output files for each process to a separate disk. If your computing cluster does not have a {\ct SHARED\_FILE\_SYSTEM}, then set this parameter to {\ct .FALSE.} on the {\ct MISC} line. This parameter is also handy for MPI jobs involving hundreds or thousands of processes, in which case writing a single Smokeview file is time-consuming. When {\ct SHARED\_FILE\_SYSTEM} is set to {\ct .FALSE.}, the file that Smokeview reads is broken into pieces, one for each MPI process. By doing this, you avoid serially writing to the Smokeview file. One other useful parameter for larger MPI jobs is called {\ct VERBOSE} on the {\ct MISC} line. This logical parameter suppresses information related to MPI process and OpenMP thread assignments that is printed to the diagnostic output files. By default, its value is {\ct .TRUE.} for MPI jobs involving 50 or less processes, and {\ct .FALSE.} for larger jobs.


\subsection{Mesh Alignment}
\label{info:mesh_alignment}

Whether the calculation is to be run using MPI or not, the rules of prescribing multiple meshes are similar, with some issues to keep in mind. The most important rule of mesh alignment is that abutting cells ought to have the same cross sectional area, or integral ratios, as shown in Fig.~\ref{fig:meshes}.
\begin{figure}[p]
\begin{picture}(325,600)(0,-20)
\setlength{\unitlength}{0.015in}

\newsavebox{\mygraph}
\savebox{\mygraph}{
\begin{picture}(0,0)
\thinlines
\multiput( 0,20)(0,20){3}{\line(1,0){100}}
\multiput(20, 0)(20,0){4}{\line(0,1){80}}
\thicklines
\put(0,0){\framebox(100,80){ }}
\end{picture} }

\newsavebox{\myfinegraph}
\savebox{\myfinegraph}{
\begin{picture}(0,0)
\thinlines
\multiput( 0,10)(0,10){7}{\line(1,0){100}}
\multiput(10, 0)(10,0){9}{\line(0,1){80}}
\thicklines
\put(0,0){\framebox(100,80){ }}
\end{picture} }

\newsavebox{\myotherfinegraph}
\savebox{\myotherfinegraph}{
\begin{picture}(0,0)
\thinlines
\multiput( 0, 8)(0, 8){9}{\line(1,0){100}}
\multiput(10, 0)(10,0){9}{\line(0,1){80}}
\thicklines
\put(0,0){\framebox(100,80){ }}
\end{picture} }

\put(  0,420){\usebox{\mygraph}}
\put(100,420){\usebox{\mygraph}}
\put(230,470){\parbox{2.5in}{This is the ideal kind of mesh to mesh alignment.}}

\put(  0,320){\usebox{\mygraph}}
\put(100,320){\usebox{\myfinegraph}}
\put(230,370){\parbox{2.5in}{This is allowed so long as there are an integral number of fine cells abutting each coarse cell.}}

\put(  0,200){\usebox{\mygraph}}
\put( 80,220){\usebox{\myfinegraph}}
\put(230,270){\parbox{2.5in}{This is allowed, but of questionable value.}}

\put(  0,100){\usebox{\mygraph}}
\put( 80,110){\usebox{\myfinegraph}}
\put(230,160){\parbox{2.5in}{This is not allowed because each large cell must be completely covered by small ones.}}

\put(  0,  0){\usebox{\mygraph}}
\put(100,  0){\usebox{\myotherfinegraph}}
\put(230, 50){\parbox{2.5in}{This is not allowed.}}
\end{picture}

\caption[Rules governing the alignment of meshes]{Rules governing the alignment of meshes.}
\label{fig:meshes}
\end{figure}
The following rules of thumb should also be followed when setting up a multiple mesh calculation:
\begin{itemize}
\item Avoid putting mesh boundaries where critical action is expected, especially fire. Sometimes fire spread from mesh to mesh cannot be avoided, but if at all possible try to keep mesh interfaces relatively free of complicated phenomena since the exchange of information across mesh boundaries is not yet as accurate as cell to cell exchanges within one mesh.
\item In general, there is little advantage to overlapping meshes because information is only exchanged at exterior boundaries. This means that a mesh that is completely embedded within another receives information at its exterior boundary, but the larger mesh receives no information from the mesh embedded within. Essentially, the larger, usually coarser, mesh is doing its own simulation of the scenario and is not affected by the smaller, usually finer, mesh embedded within it. Details within the fine mesh, especially related to fire growth and spread, may not be picked up by the coarse mesh. In such cases, it is preferable to isolate the detailed fire behavior within one mesh, and position coarser meshes at the exterior boundary of the fine mesh. Then the fine and coarse meshes mutually exchange information.
\item Be careful when using the shortcut convention of declaring an entire face of the domain to be an {\ct OPEN} vent. Every mesh takes on this attribute. See Section~\ref{info:VENT} for more details.
\item If a planar obstruction is close to where two meshes abut, make sure that each mesh ``sees'' the obstruction. If the obstruction is even a millimeter outside of one of the meshes, that mesh does not account for it, in which case information is not transferred properly between meshes.
\end{itemize}
If you would like to check the mesh alignment without running the case, set {\ct CHECK\_MESH\_ALIGNMENT} to {\ct .TRUE.} on any {\ct MESH} line. If the job stops with no errors, the meshes obey the alignment rules. This check can sometimes take a few tens of seconds, but you can open Smokeview after launching the job to check the alignment by eye.


\subsubsection{Accuracy of the Multiple Mesh Calculation}

Experiment with different mesh configurations using relatively coarse mesh cells to ensure that information is being transferred properly from mesh to mesh. There are two issues of concern. First, does it appear that the flow is being badly affected by the mesh boundary? If so, try to move the mesh boundaries away from areas of activity. Second, is there too much of a jump in cell size from one mesh to another? If so, consider whether the loss of information moving from a fine to a coarse mesh is tolerable.




\subsection{Mesh Stretching: The \texorpdfstring{{\tt TRNX}}{TRNX}, \texorpdfstring{{\tt TRNY}}{TRNY} and \texorpdfstring{{\tt TRNZ}}{TRNZ} Namelist Groups (Table \ref{tbl:TRNX})}
\label{info:TRNX}

By default the mesh cells that fill the computational domain are uniform in size. However, it is possible to specify that the cells be non-uniform in one or two\footnote{If you are stretching the mesh in two coordinate directions, limit the number of cells to approximately 1~million. The Poisson solver that is used for two-coordinate stretching exhibits floating point overflow errors during the initialization phase when very large meshes are used. If you require more than a million cells, consider using multiple meshes instead of one large mesh.}
\begin{figure}[ht]
\begin{minipage}[t]{3.1in}
\includegraphics[width=3.1in]{SCRIPT_FIGURES/piece_wise_linear_trnx}
\vspace{-.2in}
\caption[Piecewise-linear mesh transformation]{Piecewise-linear mesh transformation.}
\label{fig:grid2}
\end{minipage}
\hfill
\begin{minipage}[t]{3.1in}
\includegraphics[width=3.1in]{SCRIPT_FIGURES/polynomial_trnx}
\vspace{-.2in}
\caption[Polynomial mesh transformation]{Polynomial mesh transformation.}
\label{fig:grid1}
\end{minipage}
\end{figure}
of the three coordinate directions. For a given coordinate direction, $x$, $y$ or $z$, a function can be prescribed that transforms the uniformly-spaced mesh to a non-uniformly spaced mesh. {\bf Be careful with mesh transformations!}  If you shrink cells in one region you must stretch cells somewhere else. When one or two coordinate directions are transformed, the aspect ratio of the mesh cells in the 3D mesh will vary. To be on the safe side, transformations that alter the aspect ratio of cells beyond 2 or 3 should be avoided. Keep in mind that the large eddy simulation technique is based on the assumption that the numerical mesh should be fine enough to allow the formation of eddies that are responsible for the mixing. In general, eddy formation is limited by the largest dimension of a mesh cell, thus shrinking the mesh resolution in one or two directions may not necessarily lead to a better simulation if the third dimension is large. Transformations, in general, reduce the efficiency of the computation, with two coordinate transformations impairing efficiency more than a transformation in one coordinate direction. Experiment with different meshing strategies to see how much of a penalty you will pay.

Here is an example of how to do a mesh transformation. Suppose your mesh is defined
\begin{lstlisting}
&MESH IJK=15,10,20, XB=0.0,1.5,1.2,2.2,3.2,5.2 /
\end{lstlisting}
and you want to alter the uniform spacing in the $x$ direction. First, refer to the figures above. You need to define a function $x = f(\xi)$ that maps the uniformly-spaced {\em Computational Coordinate} ({\ct CC}) $0 \le \xi \le 1.5$ to the {\em Physical Coordinate} ({\ct PC}) $0 \le x \le 1.5$. The function has three mandatory constraints: it must be monotonic (always increasing), it must map $\xi=0$ to $x=0$, and it must map $\xi=1.5$ to $x=1.5$. The default transformation function is $f(\xi) = \xi$ for a uniform mesh, but you need not do anything in this case.

Two types of transformation functions are allowed. The first, and simplest, is a piecewise-linear function. Figure~\ref{fig:grid2} gives an example of a piecewise-linear transformation. The graph indicates how 15 uniformly spaced mesh cells along the horizontal axis are transformed into 15 non-uniformly spaced cells along the vertical axis. In this case, the function is made up of straight line segments connecting points ({\ct CC},{\ct PC}), in increasing order, as specified by the following lines in the input file:
\begin{lstlisting}
&TRNX CC=0.30, PC=0.50, MESH_NUMBER=2 /
&TRNX CC=1.20, PC=1.00, MESH_NUMBER=2 /
\end{lstlisting}
The integer {\ct MESH\_NUMBER} indicates which mesh to apply the transformation. If you want the transformation to be applied to all meshes, set {\ct MESH\_NUMBER} to 0. The parameter {\ct CC} refers to the Computational Coordinate, $\xi$, located on the horizontal axis; {\ct PC} is the Physical Coordinate, $x$, located on the vertical axis.  The slopes of the line segments in the plot indicate whether the mesh is being stretched (slopes greater than 1) or shrunk (slopes less than 1). The tricky part about this process is that you usually have a desired shrinking/stretching strategy for the Physical Coordinate on the vertical axis, and must work backwards to determine what the corresponding points should be for the Computational Coordinate on the horizontal axis. Note that the above transformation is applied to the second mesh in a multiple mesh job.
It should be also noted that the start and endpoints should not be specified in this linear grid transformation.

The second type of transformation is a polynomial function whose constraints are of the form
\[ \frac{\d^n f(\hbox{\ct CC})}{\d\xi^n} = \hbox{\ct PC}   \]
Figure~\ref{fig:grid1} gives an example of a polynomial transformation, for which the parameters are specified (assuming that this is the third mesh):
\begin{lstlisting}
&TRNX IDERIV=0, CC=0.75, PC=0.75, MESH_NUMBER=3 /
&TRNX IDERIV=1, CC=0.75, PC=0.50, MESH_NUMBER=3 /
\end{lstlisting}
which correspond to the constraints
$f(0.75)=0.75$ and $\frac{\d f}{\d \xi}(0.75) = 0.5$, or, in words, the
function maps 0.75 into 0.75 and the slope of the function at
$\xi=0.75$ is 0.5~.
The transform function must also pass through the points (0,0) and (1.5,1.5), meaning that FDS must compute the coefficients for the cubic polynomial $f(\xi) = c_0 + c_1 \, \xi + c_2 \, \xi^2 + c_3 \, \xi^3$. More constraints on the function lead to higher order polynomial functions, so be careful about too many constraints which could lead to non-monotonic functions. The monotonicity of the function is checked by the program and an error message is produced if it is not monotonic.

Do not specify either linear transformation points or {\ct IDERIV=0} points at coordinate values corresponding to the mesh boundaries. This is done automatically by FDS.


\subsection{Mesh Resolution}
\label{info:Mesh_Resolution}

A common question asked by new FDS users is, ``What should my grid spacing be?'' The answer is not easy because it depends considerably on what you are trying to accomplish. In general, you should build an FDS input file using a relatively coarse mesh, and then gradually refine the mesh until you do not see appreciable differences in your results. This is referred to as a mesh sensitivity study.

For simulations involving buoyant plumes, a measure of how well the flow field is resolved is given by the non-dimensional expression $D^*/\dx$, where $D^*$ is a characteristic fire diameter
\be D^* = \left(
     \frac{\dQ}{\rho_\infty \, c_p \, T_\infty \, \sqrt{g} }
     \right)^\frac{2}{5}  \ee
and $\dx$ is the nominal size of a mesh cell\footnote{The characteristic fire diameter is related to the characteristic fire size via the relation $Q^* = (D^*/D)^{5/2}$, where $D$ is the physical diameter of the fire.}. The quantity, $\dQ$, is the total heat release rate of the fire. If it changes over time, you should consider the corresponding change in resolution. The quantity $D^*/\dx$ can be thought of as the number of computational cells spanning the characteristic (not necessarily the physical) diameter of the fire. The more cells spanning the fire, the better the resolution of the calculation. It is better to assess the quality of the mesh in terms of this non-dimensional parameter, rather than an absolute mesh cell size. For example, a cell size of 10~cm may be ``adequate,'' in some sense, for evaluating the spread of smoke and heat through a building from a sizable fire, but may not be appropriate to study a very small, smoldering source.

The FDS Validation Guide~\cite{FDS_Validation_Guide} contains a table of the values of $D^*/\dx$ used in the simulation of the validation experiments. The table is near the end of the chapter that describes all the experiments. These values range over two orders of magnitude and were chosen based on a grid resolution study and the particular attributes of the given fire scenario. It would be inappropriate to take any of these values as an ``acceptable'' minimum.

There are a number of special output quantities that provide local measures of grid resolution. See Section~\ref{info:meshquality} for details.






\chapter{Global Simulation Parameters}
\label{info:MISC}

{\ct MISC} is the namelist group of input parameters that do not fall into any one category (Table~\ref{tbl:MISC}). They are typically global in extent, like the ambient temperature. Only one {\ct MISC} line should be entered in the data file. For example, the input line
\begin{lstlisting}
&MISC TMPA=25. /
\end{lstlisting}
sets the ambient temperature at 25~$^\circ$C. The following sections describe the various miscellaneous parameters.

\section{Ambient Conditions}
\label{info:MISC_Basics}

You can set the ambient temperature and pressure using the following parameters:
\begin{description}
\item[{\ct P\_INF}] Background pressure (at the ground) in Pa. The default is 101325 Pa.
\item[{\ct TMPA}] Ambient temperature, the temperature of everything at the start of the simulation. The default is 20~$^\circ$C.
\end{description}


\section{Simulation Mode}
\label{Sim_Mode}

There are four basic modes of operation in FDS: {\ct 'DNS'} (Direction Numerical Simulation), {\ct 'LES'} (Large Eddy Simulation), {\ct 'VLES'} (Very Large Eddy Simulation), and {\ct 'SVLES'} (Simple Very Large Eddy Simulation---VLES with simplified physics). These modes govern a number of physical and numerical parameters that determine the level of physics and the accuracy of the numerical model. They are specified using {\ct SIMULATION\_MODE} on the {\ct MISC} line. For example
\begin{lstlisting}
&MISC ..., SIMULATION_MODE='DNS' /
\end{lstlisting}
indicates a direct numerical simulation\footnote{Prior versions specified a DNS using {\ct DNS=.TRUE.} on the {\ct MISC} line.}. The default value is {\ct 'VLES'}.

Table~\ref{tbl:SIMULATION_MODE} indicates the value of various parameters for each of the four simulation modes and the sections where these parameters are explained in detail.

\begin{table}[ht]
\centering
\caption{Parameters effected by {\ct SIMULATION\_MODE}.}
\label{tbl:SIMULATION_MODE}
\begin{tabular}{|l|c|c|c|c|c|}
\hline
Key Parameter                          & Section                        & {\ct 'DNS'} & {\ct 'LES'}  & {\ct 'VLES'}  & {\ct 'SVLES'}  \\ \hline \hline
{\ct BAROCLINIC}                       & \ref{baroclinic_torque}        & T           & T            & T             & F              \\ \hline
{\ct CFL\_VELOCITY\_NORM}              & \ref{info:CFL}                 & 1           & 1            & 0             & 3              \\ \hline
{\ct CHECK\_VN}                        & \ref{info:VN}                  & T           & T            & T             & F              \\ \hline
{\ct CONSTANT\_SPECIFIC\_HEAT\_RATIO}  & \ref{info:Enthalpy}            & F           & F            & F             & T              \\ \hline
{\ct MAX\_PRESSURE\_ITERATIONS}        & \ref{pressure_solver}          & 10          & 10           & 10            & 3              \\ \hline
{\ct PROJECTION}                       & \ref{pressure_solver}          & T           & T            & F             & F              \\ \hline
{\ct NEAR\_WALL\_TURBULENCE\_MODEL}    & \ref{info:LES}                 & None        & WALE         & Van Driest    & Van Driest     \\ \hline
\end{tabular}
\end{table}


\section{Stopping and Restarting Calculations}
\label{info:restart}

An important {\ct MISC} parameter is called {\ct RESTART}. Normally, a simulation consists of a sequence of events starting from ambient conditions. However, there are occasions when you might want to stop a calculation, make a few limited adjustments, and then restart the calculation from that point in time. To do this, first bring the calculation to a halt gracefully by creating a file called {\ct CHID.stop} in the directory where the output files are located. Remember that FDS is case-sensitive. The file name must be exactly the same as the {\ct CHID} and `stop' should be lower case. FDS checks for the existence of this file at each time step, and if it finds it, gracefully shuts down the calculation after first creating a final Plot3D file and a file (or files in the case of a multiple mesh job) called {\ct CHID.restart} (or {\ct CHID\_nn.restart}). To restart a job, the file(s) {\ct CHID.restart} should exist in the working directory, and the phrase {\ct RESTART=.TRUE.} needs to be added to the {\ct MISC} line of the input data file. For example, suppose that the job whose {\ct CHID} is ``plume'' is halted by creating a dummy file called {\ct plume.stop} in the directory where all the output files are being created. Note you wil also need to delete the file {\ct CHID.stop} so that FDS does not immediately stop the calculation. To restart this job from where it left off, add {\ct RESTART=.TRUE.} to the {\ct MISC} line of the input file {\ct plume.fds}, or whatever you have chosen to name the input file. The existence of a restart file with the same {\ct CHID} as the original job tells FDS to continue saving the new data in the same files as the old\footnote{By default, when a job is restarted, the spreadsheet output files will be appended at the time the job was restarted, not the time the job was stopped. If you want the output files to be appended without clipping off any existing data, even though some duplicate output will be left over, then set {\ct CLIP\_RESTART\_FILES} to {\ct .FALSE.} on the {\ct DUMP} line.}.  If {\ct RESTART\_CHID} is also specified on the {\ct MISC} line, then FDS will look for old output files tagged with this string instead of using the specified {\ct CHID} on the {\ct HEAD} line. In this case, the new output files will be tagged with {\ct CHID}, and the old output files will not be altered. When running the restarted job, the diagnostic output of the restarted job is appended to output files from the original job.

There may be times when you want to save restart files periodically during a run as insurance against power outages or system crashes. If this is the case, at the start of the original run set {\ct DT\_RESTART=50.} on the {\ct DUMP} line to save restart files every 50~s, for example. The default for {\ct DT\_RESTART} is 1000000, meaning no restart files are created unless you gracefully stop a job by creating a dummy file called {\ct CHID.stop}.
It is also possible to use the new control function feature (see Section~\ref{info:CTRL}) to stop a calculation or dump a restart file when the computation reaches some measurable condition such as a first sprinkler activation.

Between job stops and restarts, major changes cannot be made in the calculation like adding or removing vents and obstructions. The changes are limited to those parameters that do not instantly alter the existing flow field. Since the restart capability has been used infrequently by the developers, it should be considered a fragile construct. Examine the output to ensure that no sudden or unexpected events occur during the stop and restart.








\section{Gravity}
\label{info:GVEC}

By default, gravity points in the negative $z$ direction, or more simply, downward. However, to change the direction of gravity to model a sloping roof or tunnel, for example, specify the gravity vector on the {\ct MISC} line with a triplet of numbers of the form {\ct GVEC=0.,0.,-9.81}, with units of m/s$^2$. This is the default, but it can be changed to be any direction.

There are a few special applications where you might want to vary the gravity vector as a function of time or as a function of the first spatial coordinate, $x$. For example, on board space craft, small motions can cause temporal changes in the normally zero level of gravity, an effect known as ``g-jitter.'' More commonly, in tunnel fire simulations, it is sometimes convenient to change the direction of gravity to mimic the change in slope. The slope of the tunnel might change as you travel through it; thus, you can tell FDS where to redirect gravity. For either a spatially or temporally varying direction and/or magnitude of gravity, do the following. First, on the {\ct MISC} line, set the three components of gravity, {\ct GVEC}, to some ``base'' state like {\ct GVEC=1.,1.,1.}, which gives you the flexibility to vary all three components. Next, designate ``ramps'' for the individual components, {\ct RAMP\_GX}, {\ct RAMP\_GY}, and {\ct RAMP\_GZ}, all of which are specified on the {\ct MISC} line. There is more discussion of {\ct RAMP}s in Section~\ref{info:RAMP}, but for now you can use the following as a simple template to follow:
\begin{lstlisting}
&MISC GVEC=1.,0.,1., RAMP_GX='x-ramp', RAMP_GZ='z-ramp' /

&RAMP ID='x-ramp', X=  0., F=0.0 /
&RAMP ID='x-ramp', X= 50., F=0.0 /
&RAMP ID='x-ramp', X= 51., F=-0.49 /
&RAMP ID='x-ramp', X=100., F=-0.49 /

&RAMP ID='z-ramp', X=  0., F=-9.81 /
&RAMP ID='z-ramp', X= 50., F=-9.81 /
&RAMP ID='z-ramp', X= 51., F=-9.80 /
&RAMP ID='z-ramp', X=100., F=-9.80 /
\end{lstlisting}
Note that both the $x$ and $z$ components of gravity are functions of $x$. FDS has been programmed to only allow variation in the $x$ coordinate. Note also that {\ct F} is just a multiplier of the ``base'' gravity vector components, given by {\ct GVEC}. This is why using the number 1 is convenient -- it allows you to specify the gravity components on the {\ct RAMP} lines directly. The effect of these lines is to model the first 50~m of a tunnel without a slope, but the second 50~m with a 5~\% slope upwards. Note that the angle from vertical of the gravity vector due to a 5~\% slope is $\tan^{-1} 0.05=2.86^\circ$ and that 0.49 and 9.80 are equal to the magnitude of the gravity vector, 9.81~m/s$^2$, multiplied by the sine and cosine of 2.86$^\circ$, respectively. To check your math, the square root of the sum of the squares of the gravity components ought to equal 9.81. Notice in this case that the $y$ direction has been left out because there is no $y$ variation in the gravity vector.
To vary the direction and/or magnitude of gravity in time, follow the same procedure but replace the {\ct X} in the {\ct RAMP}
lines with a {\ct T}.

Note that in a case with sprinklers, changing {\ct GVEC} will change how droplets move in the gas but not how droplets move on solid sufaces. On solid surfaces droplet movement will always consider down to be the negative-z direction.

\section{Special Topic: The Baroclinic Vorticity}
\label{baroclinic_torque}

The pressure term in the momentum transport equation solved by FDS is decomposed as follows:
\be
   \frac{1}{\rho} \nabla \tp = \nabla \left( \frac{\tp}{\rho}\right) - \tp \, \nabla \left(\frac{1}{\rho} \right)
\ee
The pressure term is written like this so that a separable elliptic partial differential equation can be solved for the ``total'' pressure, $\cH \equiv |\bu|^2/2 + \tp/\rho$, using a direct solver. The second term is calculated based on the pressure field from the previous time step, a slight approximation necessary to render the pressure equation separable. This term is sometimes referred to as the baroclinic torque, and it is responsible for generating vorticity due to the non-alignment of pressure and density gradients. In versions of FDS prior to 6, the inclusion of the baroclinic torque term was found to sometimes cause numerical instabilities. If it is suspected that the term is responsible for numerical problems, it can be removed by setting {\ct BAROCLINIC=.FALSE.} on the {\ct MISC} line. For example, in the simple helium plume test case below, neglecting the baroclinic torque changes the puffing behavior noticeably. In other applications, however, its effect is less significant. For further discussion of its effect, see Ref.~\cite{Xin:JSS2005}.



\subsubsection{Example Case: Flowfields/helium\_2d\_isothermal}
\label{helium_2d_isothermal}

This case demonstrates the use of baroclinic correction for an axially-symmetric helium plume. Note that the governing equations solved in FDS are written in terms of a three dimensional Cartesian coordinate system. However, a two dimensional Cartesian or two dimensional cylindrical (axially-symmetric) calculation can be performed by setting the number of cells in the $y$ direction to 1. An example of an axially-symmetric helium plume is shown in Fig.~\ref{helium_plume}.

\begin{figure}[ht]
\noindent
\begin{minipage}{1.1in}
\includegraphics[height=2in]{SCRIPT_FIGURES/helium_2d_isothermal}
\end{minipage}
\hfill
\begin{minipage}{5.5in}
\begin{lstlisting}[basicstyle=\scriptsize\ttfamily]
&HEAD CHID='helium_2d_isothermal',TITLE='Axisymmetric Helium Plume' /
&MESH IJK=72,1,144 XB=0.00,0.08,-0.001,0.001,0.00,0.16, CYLINDRICAL=.TRUE. /
&TIME T_END=5.0 /
&MISC DNS=.TRUE. /
&RADI RADIATION=.FALSE. /
&SPEC ID='HELIUM'  /
&SURF ID='HELIUM', VEL=-0.673, MASS_FRACTION(1)=1.0, TAU_MF(1)=0.3 /
&VENT MB='XMAX' ,SURF_ID='OPEN' /
&VENT MB='ZMAX' ,SURF_ID='OPEN' /
&OBST XB= 0.0,0.036,-0.001,0.001,0.00,0.02, SURF_IDS='HELIUM','INERT','INERT' /
&DUMP PLOT3D_QUANTITY(1)='PRESSURE',PLOT3D_QUANTITY(5)='HELIUM' /
&SLCF PBY=0.000,QUANTITY='DENSITY', VECTOR=.TRUE. /
&SLCF PBY=0.000,QUANTITY='VOLUME FRACTION', SPEC_ID='HELIUM' /
&TAIL /
\end{lstlisting}
\end{minipage}
\caption[Snapshot of the {\ct helium\_2d\_isothermal} test case]{Simulation of a helium plume.}
\label{helium_plume}
\end{figure}

\section{Special Topic: Large Eddy Simulation Parameters}
\label{info:LES}

By default FDS uses the Deardorff~\cite{Deardorff:1980,Pope:2000} turbulent viscosity,
\begin{equation}
(\mu_{\hbox{\tiny LES}}/\rho) = C_\nu \Delta \sqrt{k_{\rm sgs}}
\end{equation}
where $C_\nu=0.1$ and the subgrid scale (sgs) kinetic energy is taken from an algebraic relationship based on scale similarity (see the FDS Technical Reference Guide~\cite{FDS_Math_Guide}). The LES filter width is taken as the geometric mean of the local mesh spacing in each direction, $\Delta = (\delta x\, \delta y\, \delta z)^{(1/3)}$.

Options for the {\ct TURBULENCE\_MODEL} on the {\ct MISC} line are listed in Table~\ref{turb_table}. Note that the model used in FDS versions 1-5 is {\ct 'CONSTANT SMAGORINSKY'}. The thermal conductivity and material diffusivity are related to the turbulent viscosity by:
\be
   k_{\hbox{\tiny LES}} = \frac{\mu_{\hbox{\tiny LES}} \, c_p}{\PR_{\rm t}}
   \quad ; \quad  (\rho D)_{\hbox{\tiny LES}} =\frac{\mu_{\hbox{\tiny LES}}}{\SC_{\rm t}}
\ee
The turbulent Prandtl number $\PR_t$ and the turbulent Schmidt number $\SC_t$ are assumed to be constant for a given scenario. Although it is not recommended for most calculations, you can modify $\PR_{\rm t}=0.5$, and $\SC_{\rm t}=0.5$ via the parameters {\ct PR}, and {\ct SC} on the {\ct MISC} line. A more detailed discussion of these parameters is given in the FDS Technical Reference Guide~\cite{FDS_Math_Guide}.

\begin{table}[ht]
\caption[Turbulence model options]{Turbulence model options.}
\label{turb_table}
\centering
\begin{tabular}{|lll|}
\hline
{\ct TURBULENCE\_MODEL} \hfill  & Description    \hfill                                         & Coefficient(s)  \hfill  \\ \hline
{\ct 'CONSTANT SMAGORINSKY'}    & Constant coefficient Smagorinsky model \cite{Smagorinsky:1}   & {\ct C\_SMAGORINSKY}  \\
{\ct 'DYNAMIC SMAGORINSKY'}     & Dynamic Smagorinsky model \cite{Germano:1991,Moin:1991}       & None                  \\
{\ct 'DEARDORFF'}               & Deardorff model \cite{Deardorff:1980,Pope:2000}               & {\ct C\_DEARDORFF}    \\
{\ct 'VREMAN'}                  & Vreman's eddy viscosity model \cite{Vreman:2004}              & {\ct C\_VREMAN}       \\
{\ct 'RNG'}                     & Renormalization group eddy viscosity model \cite{Yakhot:1989} & {\ct C\_RNG}, {\ct C\_RNG\_CUTOFF} \\
{\ct 'WALE'}                    & Wall-Adapting Local Eddy-viscosity model \cite{Nicoud:1999}   & {\ct C\_WALE} \\ \hline
\end{tabular}
\end{table}

\subsubsection*{Near-Wall Turbulence Model}

By default, FDS uses constant coefficient Smagorinsky \cite{Smagorinsky:1} with Van Driest damping (see \cite{Wilcox:1}) for the eddy viscosity in the first off-wall grid cell because the test filtering operation for the Deardorff model is ill-defined near the wall.  The damping function is added to the eddy viscosity so that the viscosity goes to zero at the correct rate as you approach the wall where the no slip condition applies.

An alternative to the damping function is to use the WALE model of Nicoud and Ducros \cite{Nicoud:1999}.  To implement WALE as the near-wall model use {\ct NEAR\_WALL\_TURBULENCE\_MODEL='WALE'} on the {\ct MISC} line.  Note that even if you have set WALE as the bulk turbulence model, you must also explicitly set WALE as the near-wall turbulence model if that is desired.






\section{Special Topic: Numerical Stability Parameters}
\label{info:Stability_Constraints}

FDS uses an explicit time advancement scheme; thus, the time step plays an important role in maintaining numerical stability and accuracy. Below we examine the constraints on the time step necessary for stability in the presence of advection, diffusion, and expansion of the velocity and scalar fields. In addition, there are additional constraints that ensure accuracy of various algorithms.

\subsection{The Courant-Friedrichs-Lewy (CFL) Constraint}
\label{info:CFL}

The well-known CFL constraint given by
\begin{equation}
\mbox{CFL} = \delta t \frac{\|\mathbf{u}\|}{\Delta} < 1
\end{equation}
places a restriction on the time step due to the advection velocity.  The limits for the CFL are set by {\ct CFL\_MIN} (default 0.8) and {\ct CFL\_MAX} (default 1) on {\ct MISC}. Physically, the constraint says that a fluid element should not traverse more than one cell width, $\Delta$, within one time step, $\delta t$. For LES, this constraint has the added advantage of keeping the implicit temporal and spatial filters consistent with each other. In other words, in order to resolve an eddy of size $\Delta$, the time step needs to obey the CFL constraint. If one were to employ an implicit scheme for the purpose of taking time steps ten times larger than the CFL limit, the smallest resolvable turbulent motions would then be roughly ten times the grid spacing, which would severely limit the benefit of using LES.  In most cases, if you want the simulation to run faster, a better strategy is to coarsen the grid resolution while keeping the CFL close to 1.

The exact CFL needed to maintain stability depends on the order (as well as other properties) of the time integration scheme and the choice of velocity norm. Four choices for velocity norm are available in FDS (set on {\ct MISC}):
\vskip\baselineskip
\noindent
{\ct CFL\_VELOCITY\_NORM=0} (VLES default, corresponds to $L_\infty$ norm of velocity vector)
    \begin{equation}
    \frac{\|\mathbf{u}\|}{\Delta} = \max \left(\frac{|u|}{\delta x}, \frac{|v|}{\delta y}, \frac{|w|}{\delta z}\right) + |\nabla \cdot \bu|
    \end{equation}
{\ct CFL\_VELOCITY\_NORM=1} (DNS and LES defaults, most restrictive, corresponds to $L_1$ norm of velocity vector)
    \begin{equation}
    \frac{\|\mathbf{u}\|}{\Delta} = \frac{|u|}{\delta x}+\frac{|v|}{\delta y}+\frac{|w|}{\delta z} + |\nabla \cdot \bu|
    \end{equation}
{\ct CFL\_VELOCITY\_NORM=2} ($L_2$ norm of velocity vector)
    \begin{equation}
    \frac{\|\mathbf{u}\|}{\Delta} = \sqrt{ \left( \frac{u}{\delta x} \right)^2 + \left( \frac{v}{\delta y} \right)^2 + \left( \frac{w}{\delta z} \right)^2 } + |\nabla \cdot \bu|
    \end{equation}
{\ct CFL\_VELOCITY\_NORM=3} (SVLES default, least restrictive, corresponds to $L_\infty$ norm of velocity vector without the velocity divergence)
    \begin{equation}
    \frac{\|\mathbf{u}\|}{\Delta} = \max \left(\frac{|u|}{\delta x}, \frac{|v|}{\delta y}, \frac{|w|}{\delta z}\right)
    \end{equation}
The last listed form of the constraint is the least restrictive, but also the most dangerous in the sense that a numerical instability is more likely to occur when the CFL constraint is least restrictive. This option is akin to a high optimization level of a computer program compiler---there is a trade-off between added speed and added risk of failure.

Notice that the CFL norms 0-2 include the divergence of the velocity field. This is an added safeguard because often numerical instabilities arise when there is a sudden release of energy and a corresponding increase in the divergence within a single grid cell. In an explicit Euler update of the continuity equation, if the time increment is too large the grid cell may be totally drained of mass, which, of course, is not physical. The constraint $\rho^{n+1}>0$ therefore leads to the following restriction on the time step:
\begin{equation}
\label{eqn_dtmassrestrict}
\delta t < \frac{\rho^n}{\overline{\mathbf{u}}^n\cdot\nabla\rho^n + \rho^n \nabla\cdot\mathbf{u}^n}
\end{equation}
We can argue that the case we are most concerned with is when $\rho^n$ is near zero.  A reasonable approximation to (\ref{eqn_dtmassrestrict}) then becomes
\be
\label{eqn_divstability}
\delta t < \frac{\rho}{\overline{u}_i \left(\frac{\rho-0}{\delta x_i}\right) + \rho \nabla\cdot\mathbf{u}}
  = \left[ \frac{\overline{u}_i}{\delta x_i} + \nabla\cdot\mathbf{u} \right]^{-1}
\ee
Eq.~(\ref{eqn_divstability}) basically adds the effect of thermal expansion to the CFL constraint.


\subsection{The Von Neumann Constraint}
\label{info:VN}

The Von Neumann constraint is given by
\begin{equation}
\mbox{VN} \equiv  2 \; \delta t \; \max \left[ \frac{\mu}{\rho},D_\alpha \right] \; \left( \frac{1}{\delta x^2}+\frac{1}{\delta y^2}+\frac{1}{\delta z^2} \right) < 1
\end{equation}
The limits for VN may be adjusted using {\ct VN\_MIN} (default 0.8 for all forms of LES, 0.4 for DNS) and {\ct VN\_MAX} (default 1.0 for all forms of LES, 0.5 for DNS) on {\ct MISC}. We can understand this constraint in a couple of different ways.  First, we could consider the model for the diffusion velocity of species $\alpha$ in direction $i$, $V_{\alpha,i} Y_\alpha = -D_\alpha \; \partial Y_\alpha/\partial x_i$, and we would then see that VN is simply a CFL constraint due to diffusive transport.

We can also think of VN in terms of a total variation diminishing (TVD) constraint.  That is, if we have variation (curvature) in the scalar field, we do not want to create spurious oscillations that can lead to an instability by overshooting the smoothing step.  Consider the following explicit update of the heat equation for $u$ in 1-D. Here subscripts indicate grid indices and $\nu$ is the diffusivity.
\begin{equation}
u_i^{n+1} = u_i^n + \frac{\delta t \, \nu}{\delta x^2} (u_{i-1}^n - 2u_i^n + u_{i+1}^n )
\end{equation}
Very simply, notice that if $\delta t \, \nu/\delta x^2 = 1/2$ then $u_i^{n+1} = (u_{i-1}^n + u_{i+1}^n)/2$.  If the time step is any larger we overshoot the straight line connecting neighboring cell values.  Of course, this restriction is only guaranteed to be TVD if the $u$ field is ``smooth''; otherwise, the neighboring cell values may be shifted in the opposite direction.  Unfortunately, in LES there is no such guarantee and so the VN constraint can be particularly devilish in generating instabilities. For this reason, some practitioners like to employ implicit methods for the diffusive terms.



\subsection{Stability of particle transport}
\label{info:PART_Stability}

The movement of Lagrangian particles over the course of a time step is calculated using an analytical solution and remains stable regardless of the time step used by the flow solver. However, if the particle moves over the width of several grid cells in a single time step, the momentum transferred between the particle and the gas cannot be allocated properly to all of the affected cells. To overcome this problem, FDS subdivides the gas phase time step based on each particle's velocity. For example, if the particle travels across two cells in a single gas phase time step, then its trajectory is calculated by subdividing the time step into two.

In some cases with extremely fast particles, however, the stability of the overall flow behavior may require setting an additional parameter that limits the time step of the flow solver according to the speed of the fastest particle in the simulation.  The actual value of of the constraint is set using {\ct PARTICLE\_CFL\_MAX} on the {\ct MISC} line. A value of 1 (default) means that the fastest moving particle can move a distance of one grid cell during the time step. Because very fast nozzle velocities can cause extremely small time steps and hence very long run times, the {\ct PARTICLE\_CFL} constraint is set to {\ct .FALSE.} by default.  Setting {\ct PARTICLE\_CFL} to {\ct .TRUE.} on the {\ct MISC} line activates this constraint.

One additional parameter might be useful in some special cases. The numerical transport scheme for particles is first order accurate in time. If you want to improve the accuracy of the scheme, set \linebreak[4] {\ct SECOND\_ORDER\_PARTICLE\_TRANSPORT} to {\ct .TRUE.} on the {\ct PART} line. There is an increased computational cost incurred by this option, so check whether or not the extra cost is worth the extra accuracy. For most applications, given the relatively small time step of the gas phase solver, and the subdivision of the particle trajectory calculation to enforce a local particle CFL constraint, the improved accuracy is not worth the additional cost.


\subsection{Heat Transfer Constraint}
\label{info:HT}

Note that the heat flux, $\dot{q}''_{\rm c}$, has units of \si{W/m$^2$}.  Thus, a velocity scale may be formed from $(\dot{q}''_{\rm c}/\rho_{\rm w})^{1/3}$, where $\rho_{\rm w}$ is the gas phase density at the wall. Anytime we have a velocity scale to resolve, we have a CFL-type stability restriction. Therefore, the heat transfer stability check loops over all wall cells to ensure $\delta t < (\delta x/2) / (\dot{q}''_{\rm c}/\rho_{\rm w})^{1/3}$. This check is invoked by setting {\ct CHECK\_HT=.TRUE.} on the {\ct MISC} line. It is {\ct .FALSE.} by default.





\section{Special Topic: Flux Limiters}
\label{info:flux_limiters}

FDS employs \emph{total variation diminishing} (TVD) schemes for scalar transport.  The default for VLES (FDS default {\ct SIMULATION\_MODE}) is Superbee \cite{Roe:1986}, so chosen because this scheme does the best job preserving the scalar variance in highly turbulent flows with coarse grid resolution.  The default scheme for DNS and LES is CHARM \cite{Zhou:1995} because the gradient steepening used in Superbee forces a stair step pattern at high resolution, while CHARM is convergent.   A few other schemes (including Godunov and central differencing) are included for completeness; more details can be found in the Tech Guide \cite{FDS_Tech_Guide}.  Table \ref{tab:flux_limiters} below shows the character strings which may be used to invoke the various limiter schemes.

\begin{lstlisting}
&MISC FLUX_LIMITER='GODUNOV' / ! invoke Godunov (first-order upwind scheme)
\end{lstlisting}

\begin{table}[ht]
\caption[Flux limiter options]{Flux limiter options.}
\label{tab:flux_limiters}
\centering
\begin{tabular}{|l|l|}
\hline
Scheme                              & {\ct FLUX\_LIMITER} \\
\hline
Central differencing                & {\ct 'CENTRAL'}  \\
Godunov                             & {\ct 'GODUNOV'}  \\
Superbee (VLES, SVLES default)      & {\ct 'SUPERBEE'}  \\
MINMOD                              & {\ct 'MINMOD'}  \\
CHARM (DNS, LES default)            & {\ct 'CHARM'}  \\
MP5                                 & {\ct 'MP5'}  \\ \hline
\end{tabular}
\end{table}


\section{Background Noise}
\label{info:NOISE}

FDS initializes the flow field with a very small amount of ``noise'' to prevent the development of a perfectly symmetric flow when the boundary and initial conditions are perfectly symmetric. To turn this off, set {\ct NOISE=.FALSE.} To control the amount of noise, set {\ct NOISE\_VELOCITY}. Its default value is 0.005~m/s.



\section{Protecting Old Cases}
\label{info:OVERWRITE}

When you run a job that has been run previously, FDS will automatically overwrite the old output with new. If you do not want this to happen, set {\ct OVERWRITE=.FALSE.} on the {\ct MISC} line, in which case FDS will check for the existence of previously created output files and stop execution if they exist.

\section{Turning off the Flow Field}
\label{info:freeze_velocity}

For certain types of diagnostic tests, it is useful to turn off the velocity field and exercise some other aspect of the model, like radiation or particle transport. To do this, set {\ct FREEZE\_VELOCITY=.TRUE.} on the {\ct MISC} line.



\section{Setting Limits: The \texorpdfstring{{\tt CLIP}}{CLIP} Namelist Group (Table \ref{tbl:CLIP})}
\label{info:CLIP}

The algorithms in FDS are designed to work within a certain range of values for density, temperature and mass fraction. To prevent unphysical results, there are bounds placed on these variables to prevent a single spurious value from causing a numerical instability. It also prevents out of range errors from calls to temperature-dependent look-up tables. By default, FDS determines the lowest and highest values of the variables based on your input, but it is not possible in all cases to anticipate just how low or high a given value might be. Thus, on rare occasions you might need to set upper or lower bounds on the density or temperature. Temperature and density bounds are input under the namelist group called {\ct CLIP}. The parameters are listed in Table~\ref{tbl:CLIP}. You only need to set these values if you notice that one of them appears to be ``cut off'' when examining the results in Smokeview. For typical fire scenarios, you need not set these values, but if you anticipate relatively low or high values in an unusual case, take a look at the calculation results to determine if a change in the bounds is needed.



\chapter{Initial Conditions}
\label{info:INIT}

Typically, an FDS simulation begins at time $t=0$ with ambient conditions. The air temperature is assumed constant with height, and the density and pressure decrease with height (the $z$ direction). This decrease is not noticed in most building scale calculations, but it is important in large outdoor simulations.

There are some scenarios for which it is convenient to change the ambient conditions within rectangular regions of the domain using the namelist keyword {\ct INIT} (Table~\ref{tbl:INIT}). There can be multiple {\ct INIT} lines. IF two rectangular regions defined by {\ct INIT} overlap, it is the second of the overlapping regions that takes precedence, including default conditions. That is, it is possible to overwrite the initial conditions explicitly specified by the first {\ct INIT} line with the default initial conditions implied by the second {\ct INIT} line.

\section{Gas Species}

Species concentrations can be initialized using pairs of {\ct SPEC\_ID(N)} and {\ct MASS\_FRACTION(N)} where {\ct N} is an ordinal index starting from 1. Note that {\ct N} is not necessarily indicative of the order in which the species are listed in the input file. Also note that the background species cannot be specified when using {\ct MASS\_FRACTION}.  The mass fraction of the background species will be set to account for any mass fraction not specified with other species.
Make sure that you specify all species (components of {\ct MASS\_FRACTION(N)}) on the same {\ct INIT} line for example,
\begin{lstlisting}
&INIT XB=0.0,0.1,0.0,0.025,0.0,0.1,
      MASS_FRACTION(1)=0.21, SPEC_ID(1)='OXYGEN',
      MASS_FRACTION(2)=0.06, SPEC_ID(2)='PROPANE' /
\end{lstlisting}
Here, within the region whose bounds are given by the sextuplet {\ct XB}, the initial mass fractions of oxygen and propane will be initialized to 0.21 and 0.06, respectively. You must specify the gas species using the {\ct SPEC} namelist group. See Section~\ref{info:SPEC} for details.

{\ct VOLUME\_FRACTION} can be substituted for {\ct MASS\_FRACTION}.

\section{Temperature}

To modify the local initial temperature, add lines of the form,
\begin{lstlisting}
&INIT XB=0.0,0.1,0.0,0.025,0.0,0.1, TEMPERATURE=60. /
\end{lstlisting}
This indicates that the temperature shall be 60~$^\circ$C instead of the ambient within the bounds given by {\ct XB}. The {\ct INIT} construct may be useful in examining the influence of stack effect in a building, where the temperature is different inside and outside. If you wanted to initialize both temperature and species in the same volume, both quantities would use the same {\ct INIT} line,
\begin{lstlisting}
&INIT XB=0.0,0.1,0.0,0.025,0.0,0.1,
      MASS_FRACTION(1)=0.21, SPEC_ID(1)='OXYGEN',
      MASS_FRACTION(2)=0.06, SPEC_ID(2)='PROPANE',
      TEMPERATURE=60. /
\end{lstlisting}

\section{Density}

When specifying an initial density it is important to recognize the order in which FDS solves the governing equations. In the following example, initial species mass fractions, temperature, and density are all initialized in the same volume.
\begin{lstlisting}
&INIT XB=0.0,0.1,0.0,0.025,0.0,0.1,
      MASS_FRACTION(1)=0.21, SPEC_ID(1)='OXYGEN',
      MASS_FRACTION(2)=0.06, SPEC_ID(2)='PROPANE',
      TEMPERATURE=60., DENSITY=1.13 /
\end{lstlisting}
This example is a case where we have over-defined the problem. Since the temperature is computed from the equation of state using the specified density, the specified temperature will not, in general, satisfy the equation of state, and FDS will overwrite the specified temperature.

\section{Heat Release Rate Per Unit Volume (HRRPUV)}

The {\ct INIT} line may also be used to specify a volumetric heat source term. For example,
\begin{lstlisting}
&INIT XB=0.0,0.1,0.0,0.025,0.0,0.1, HRRPUV=1000. /
\end{lstlisting}
indicates that the region bounded by {\ct XB} shall generate 1000~kW/m$^3$. This feature is mainly useful for diagnostics, or to model a fire in a very simple way.


\section{Velocity Field}
\label{info:velo_restart}
\label{info:CSVF}

It may be useful to start a calculation from an established flow field.  Usually this can be accomplished with the normal restart functionality.  But in some circumstances restart may be fragile, or you may want to specify a profile throughout the entire domain.  For such situations we have added the ability to read the velocity field information from a comma-separated value (.csv) file.  You have the option of creating the velocity file using FDS or creating your own.  To generate the velocity initialization file with FDS, in the input file add a {\ct DUMP} line with a {\ct UVW\_TIMER} (time in seconds).  The timer will accept up to 10 values, and will write velocity files for each mesh and each timer index to the working directory.  For example, if you want to write the simulation velocity field at 10 minutes into the run, add the following:
\begin{lstlisting}
&DUMP UVW_TIMER(1)=600 /
\end{lstlisting}
FDS will then write {\ct CHID\_uvw\_{\it nn}.csv} for each time index and mesh.  The format for this file is
\begin{lstlisting}
  WRITE(LU_UVW) IMIN,IMAX,JMIN,JMAX,KMIN,KMAX
  DO K=KMIN,KMAX
   DO J=JMIN,JMAX
    DO I=IMIN,IMAX
     WRITE(LU_UVW,*) U(I,J,K),',',V(I,J,K),',',W(I,J,K)
    ENDDO
   ENDDO
  ENDDO
\end{lstlisting}
You may read in the 3-D velocity field using a {\ct CSVF} line.  For example:
\begin{lstlisting}
&CSVF UVWFILE='my_velocity_field.csv' /
\end{lstlisting}
If multiple meshes are involved, it is assumed that the {\ct CSVF} lines are provided in the input file in the same order as the meshes. For two meshes you might have the following:
\begin{lstlisting}
&CSVF UVWFILE='CHID_t001_m001.csv' /
&CSVF UVWFILE='CHID_t001_m002.csv' /
&MISC PROJECTION=.TRUE. /
\end{lstlisting}
It is recommended that you also specify {\ct PROJECTION=.TRUE.} on {\ct MISC} if the specified velocity field does not satisfy the divergence constraint to machine precision on a staggered grid (this may not even be true if an analytical solution to the Navier-Stokes equations is sampled at the staggered velocity component locations).




\chapter{Pressure}
\label{info:PRES}

Normally, you need not set any parameters related to the solution of the Poisson equation for pressure. However, there are circumstances when you might need to change default numerical values. This is done through the {\ct PRES} namelist group (Table~\ref{tbl:PRES}).

\section{Accuracy of the Pressure Solver}
\label{pressure_solver}

FDS uses a low-Mach number formulation of the Navier-Stokes equations. One of the consequences of this is that the speed of sound is assumed infinite, and that the pressure throughout the computational domain is affected, instantaneously, by local changes in the flow field. A simple example of this is when air is pushed through a tunnel. If the tunnel has forced flow at one end and an opening at the other, the volume flow at the opening is the same as that which is forced at the other end. Without any heat addition, the air is assumed incompressible. Information is passed through the tunnel instantaneously in the model via a solution of a linear system of equations for the pressure. For a single mesh, the solution of this Poisson equation for the pressure is very accurate. However, for multiple meshes, there is potentially a delay in information passing throughout the domain because by default the Poisson equation is solved on each individual mesh, without any influence from the larger computational domain. The details of the numerical approach can be found in the FDS Technical Reference Guide.

Another limitation of the pressure solver is that at solid surfaces that are not part of the boundary of the computational domain, the pressure solver enforces a no-flux boundary condition. However, it is not perfect, and it is possible to have a non-zero normal velocity at a solid surface. For most applications, this velocity is so small that it has a negligible effect on the solution.

If either the error in the normal component of the velocity at a mesh interface or at a solid boundary is large, you can reduce it by making more than the default number of calls to the pressure solver at each time step. To do so, specify {\ct VELOCITY\_TOLERANCE} on the {\ct PRES} line to be the maximum allowable normal velocity component on the solid boundary or the largest error at a mesh interface. It is in units of m/s. If you set this, experiment with different values, and monitor the number of pressure iterations required at each time step to achieve your desired tolerance. The default value is $\dx/2$, where $\dx$ is the characteristic grid cell size. The number of iterations are written out to the file {\ct CHID.out}. If you use a value that is too small, the CPU time required might be prohibitive. The maximum number of iterations for each half of the time step is given by {\ct MAX\_PRESSURE\_ITERATIONS}, also on the {\ct PRES} line. Its default value is 10.

By default, FDS will suspend the pressure iterations if the error does not drop below \linebreak[4]{\ct ITERATION\_SUSPEND\_FACTOR} (0.95, by default) of its previous value. If you do not want FDS to suspend the pressure iteration, set {\ct SUSPEND\_PRESSURE\_ITERATIONS} to {\ct .FALSE.} on the {\ct PRES} line. This will be done automatically if you change the default values of {\ct VELOCITY\_TOLERANCE} or \linebreak[4]{\ct MAX\_PRESSURE\_ITERATIONS}.

If {\ct .TRUE.}, the parameter {\ct CHECK\_POISSON} tells FDS to check that the left-hand and right-hand sides of the Poisson equation for $H$ are equivalent (see the FDS Tech Guide \cite{FDS_Math_Guide}).  The error is printed to the {\ct CHID.out} file.


\section{Optional Pressure Solver}
\label{optional_pressure_solver}

The default linear solver in FDS is the CrayFishpak FFT solver ({\ct SOLVER='FFT'}).  For non-overlapping, non-stretched meshes at the same refinement level covering a single connected domain (single pressure zone), the solver may be changed to {\ct SOLVER='UGLMAT'} on {\ct PRES}. UGLMAT enables the solution of the Poisson equation from the global discretization matrix. The solver used in this mode is the Intel\textsuperscript{\textregistered} MKL Sparse Cluster Solver. When using {\ct SOLVER='UGLMAT'}, the unknown values of the pseudo-pressure, $H$, live only in gas-phase cells.  This allows for the normal components of velocity of a solid surface to be computed exactly (no velocity penetration error).  Strictly speaking, in this mode, FDS is no longer using an ``immersed boundary method'' for flow obstructions---the pressure solution is now ``unstructured''. If the solver is defined as {\ct SOLVER='GLMAT'}, the pressure is solved in both solid and gas cells using an immersed boundary method for flow obstructions, as usual for FDS.  This mode will reproduce the exact same pressure solution as a single mesh FFT solve.  That is, velocity errors at any mesh boundaries will be eliminated. As UGLMAT and GLMAT are based on Intel\textsuperscript{\textregistered} MKL parallel LU decomposition solver, they require computation and storage of global factorization matrices. Depending on the size of the problem, these operations can be taxing on computing resources. Our tests find it suitable for problems with up to a million cells on a multicore workstation with 64 GB of RAM memory. Note that currently a single discretization matrix is built for all gas cells defined on the model, therefore the solver is not meant to be used in cases of multiple sealed compartments and pressure zones.


\subsubsection{Example Case: Pressure\_Solver/duct\_flow}
\label{duct_flow}

To demonstrate how to improve the accuracy of the pressure solver, consider the flow of air through a square duct that crosses several meshes. In the sample input file, {\ct duct\_flow.fds}, air is pushed through a 1 m$^2$ duct at 1~m/s. With no thermal expansion, the volume flow into the duct ought to equal the volume flow out of the duct. Figure~\ref{duct_flow_fig} displays the computed inflow and outflow as a function of time and the number of pressure iterations required. The default pressure solution strategy uses block-wise direct FFT solves combined with a direct forcing immersed boundary method to model flow obstructions.  Hence, there are two sources of pressure error: one at a mesh interface and one at a solid boundary.  The default pressure iteration scheme tries to drive both sources of error to the specified (or default) velocity tolerance. In the {\ct duct\_flow} case, the {\ct VELOCITY\_TOLERANCE} has been set to 0.001~m/s with {\ct MAX\_PRESSURE\_ITERATIONS} set to 1000 and the grid cell size is 0.2~m.  For the default scheme (FFT + IBM), the outflow does not match the inflow exactly because of inaccuracies at the solid and mesh boundaries.  We have also included the results using the UGLMAT solver with an unstructured pressure matrix, which allows the flow solver to enforce the impermeability condition (zero normal component of velocity) at a solid boundary.
\begin{lstlisting}
&PRES SOLVER='UGLMAT' /
\end{lstlisting}
As seen in Fig.~\ref{duct_flow_fig}, the volume flow matches perfectly and the number of required pressure iterations is one.  Whether this pressure solver strategy is most efficient likely depends on the problem and the required error tolerance.  In this particular case, the UGLMAT case runs about 25 \% faster than the default FFT case, and it is more accurate---easy choice.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=3in]{SCRIPT_FIGURES/duct_flow}
\includegraphics[width=3in]{SCRIPT_FIGURES/duct_flow_iterations}
\end{center}
\caption[Results of the {\ct duct\_flow} test case]{(Left) Volume flow into and out of a square duct. (Right) The number of pressure iterations as a function of time.}
\label{duct_flow_fig}
\end{figure}


\subsubsection{Example Case: Pressure\_Solver/dancing\_eddies}
\label{dancing_eddies}

In this example, air is pushed through a 30~cm long, two-dimensional channel at 0.5~m/s. A plate obstruction normal to the flow creates a Karman vortex street. The computational domain is divided into 4 meshes. Three simulations are performed: one in which the {\ct VELOCITY\_TOLERANCE} is set to the default value, one in which it is set to a relatively small value, and one in which the {\ct SOLVER='UGLMAT'} is used. Figure~\ref{dancing_eddies_figure} shows the downstream pressure histories for these cases compared to a simulation that uses only one mesh. The case with the tighter tolerance produces a better match to the single mesh solution, but at a higher computational cost---about a factor of 2.5 .  The {\ct SOLVER='UGLMAT'} case takes just a little longer than the default---by a factor of 1.25---but the error is machine precision.  These cases used MPI for domain decomposition, but only a single OpenMP thread.  Note, however, that the UGLMAT solver is threaded, whereas currently the FFT solver (FDS default) is not.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=3in]{SCRIPT_FIGURES/dancing_eddies_default}
\includegraphics[width=3in]{SCRIPT_FIGURES/dancing_eddies_tight}
\includegraphics[width=3in]{SCRIPT_FIGURES/dancing_eddies_uglmat}
\includegraphics[width=\textwidth]{SCRIPT_FIGURES/dancing_eddies}
\end{center}
\caption[Results of the {\ct dancing\_eddies} test cases]{(Top) Comparison of pressure traces in the channel for three different settings of {\ct VELOCITY\_TOLERANCE}, the default value (upper-left), a tighter tolerance (upper-right), machine precision from the UGLMAT solver with a single iteration (middle). (Bottom) A contour plot of the pressure after 2~s with the default tolerance.}
\label{dancing_eddies_figure}
\end{figure}

One strategy for reducing the computational cost associated with a tightened tolerance on the normal velocity at mesh boundaries is to overlap the meshes. The idea is described in detail for a non-structured mesh in Ref.~\cite{Grinberg:JCP2010}. The basic idea is that a slight overlap of meshes can lead to faster convergence of the pressure solver towards the desired level of accuracy. In the {\ct dancing\_eddies} test case, the case called {\ct dancing\_eddies\_tight} is rerun as {\ct dancing\_eddies\_tight\_overlap} where each mesh is extended an additional 10 grid cells in the longitudinal direction. This increases the work by approximately a factor of 85/75, but it reduces the number of iterations. Figure~\ref{dancing_eddies_overlap} shows the reduction in the number of pressure iterations (left) and the CPU time (right).  It can be seen that the overlap strategy does not ultimately reduce the CPU cost, whereas the UGLMAT solver reduces the cost by a factor of 0.5 by using a single iteration as shown on the left plot.

\begin{figure}[ht]
\includegraphics[width=3in]{SCRIPT_FIGURES/dancing_eddies_iterations}
\includegraphics[width=3in]{SCRIPT_FIGURES/dancing_eddies_tight_overlap}
\caption[Reduction of pressure iterations in the {\ct dancing\_eddies} test cases]{The number of pressure iterations (left) and the total CPU time (right) for overlapped and non-overlapped meshes.}
\label{dancing_eddies_overlap}
\end{figure}

\subsubsection{Special Case: True Periodic Boundaries}
\label{sec:true_periodic_boundaries}

In Section \ref{sec:periodic}, we discuss how to set periodic boundaries.  By default, in order to handle the most general case of a periodic domain with multiple meshes (imagine a periodic channel divided into several meshes), FDS treats the pressure boundary condition as what we call an ``interpolated boundary.''  This means that the matrix for the pressure Poisson equation is arranged for Dirichlet boundary conditions (the value of the solution is specified at the boundary).  This can lead to small errors in the solution and sometimes it is desirable to use the true periodic matrix for the Poisson equation.  But with the current solver (Fishpak) this is only possible for a single mesh.  If you want to implement true periodic boundaries for a single mesh case, set the appropriate \verb=FISHPAK_BC= value to zero on the \verb=PRES= line.  For example,
\begin{lstlisting}
&PRES FISHPAK_BC(1:3)=0,0,0 /
\end{lstlisting}



\section{Pressure Considerations in Long Tunnels}
\label{tunnel_demo}

A common application of FDS is tunnel fires, but simulations of fires in long, relatively tight tunnels can have spurious fluctuations in the pressure field that can lead to numerical instabilities. The root cause of the problem is the way that FDS solves the equation for the pressure, $\tp$ (the tilde indicates that this is the {\em perturbation} pressure, or pressure above background). To solve for $\tp$, an elliptic PDE is formed by taking the divergence of the momentum equation, which contains the term $\nabla \tp / \rho$. Ideally, this PDE would be of the form:
\be
   \nabla \cdot \left( \frac{1}{\rho^n} \right) \nabla \tp^{n} = \; \cdots
\ee
where $n$ indicates the current time step. However, this equation cannot be solved efficiently because the matrix of the linear system of equations that is formed when discretizing it does not have constant coefficients because the density, $\rho^n$, changes with each new time step, $n$. To get around this problem, the pressure term in the momentum equation is decomposed as follows:
\be
   \frac{1}{\rho} \nabla \tp = \nabla \left( \frac{\tp}{\rho}\right) - \tp \, \nabla \left(\frac{1}{\rho} \right) \label{p_decomp}
\ee
which leads to a Poisson equation that can be solved efficiently:
\be
   \nabla^2 \left( \frac{\tp^{n,k}}{\rho^n} \right) = \nabla \cdot \tp^{n,k-1} \, \nabla \left(\frac{1}{\rho^n} \right) + \; \cdots
\ee
The superscript $k$ indicates that this equation is solved multiple times, and $k$ indicates the iteration. With each iteration, the old and new values of $\tp$ are driven closer together. The iterations continue\footnote{Keep in mind that the pressure equation iterations continue until three criteria are satisfied. The first deals with the decomposition of the pressure term, the second deals with the normal component of velocity at internal solid surfaces, and the third deals with the mismatch of normal velocity components at mesh interfaces.} until the maximum value of the error term
\be
  \epsilon^k = \max_{ijk} \left| \nabla \cdot \left( \frac{1}{\rho^n} \right) \nabla \tp^{n,k} - \nabla^2 \left( \frac{\tp^{n,k}}{\rho^n} \right) + \nabla \cdot \tp^{n,k-1} \, \nabla \left(\frac{1}{\rho^n} \right) \right|
\ee
drops below the value of {\ct PRESSURE\_TOLERANCE} which is specified on the {\ct PRES} line. Its default value is $20/\dx^2$~s$^{-2}$, where $\dx$ is the characteristic grid cell size.

If a numerical instability occurs in a simulation involving a tunnel, you might try the following remedies:
\begin{enumerate}
\item Reduce the value of {\ct PRESSURE\_TOLERANCE} on the {\ct PRES} line to alleviate the mismatch between old and new pressure fields.
\item If you are using multiple meshes, reduce the value of {\ct VELOCITY\_TOLERANCE} on the {\ct PRES} line to force a tighter match of velocities at the mesh boundaries. The default value of {\ct VELOCITY\_TOLERANCE} (with units of m/s) is one-half the grid cell size (with units of m). You may also want to increase the value of {\ct MAX\_PRESSURE\_ITERATIONS} which has a default value of 10.
\item Create {\ct OPEN} vents at various points along the length of the tunnel, near or at the floor. This models natural leakage in the tunnel, and alleviates wild oscillations in pressure.
\end{enumerate}
A simple test case, {\ct Pressure\_Solver/tunnel\_demo.fds}, demonstrates some of the issues discussed in this section. An 8~MW fire is situated in a 4~m by 4~m by 128~m long tunnel that is sloped 10$^\circ$, closed at the lower end and open at the upper end. The tunnel is divided into 8 meshes, all the same size, with a uniform grid of 20~cm. The case runs for a relatively short amount of time, and a diagnostic file\footnote{Caution: the velocity error file can be quite large. Use it only for relatively short simulations only.} containing information about the velocity and pressure errors is printed out. This file is generated by setting {\ct VELOCITY\_ERROR\_FILE} to {\ct .TRUE.} on the {\ct DUMP} line. The name of the file is {\ct tunnel\_demo\_pressit.csv}. Column~1 of the file is the time step iteration. Column~2 is the pressure iteration within the time step. Column~3 is the total number of pressure iterations for the entire simulation. Columns~4-7 contain the mesh and cell indices where the maximum velocity error occurs, which is listed in Column~8\footnote{The velocity error is the maximum value of the difference between normal velocity components at mesh interfaces or at solid internal boundaries.}. Columns~9-12 contain the mesh and cell indices where the maximum pressure error occurs, which is listed in Column~13.

Figure~\ref{tunnel_demo_fig} shows the velocity and pressure errors over a short span of the simulation. For each quantity, there is a default error tolerance which may or may not be reached depending on whether or not the {\ct MAX\_PRESSURE\_ITERATIONS} (default 10) has been reached, or whether or not the error is reduced by at least 25~\% over the previous iteration. In some situations, the error decreases slowly, and these criteria have been added to avoid excessive iterations that lead to little improvement in accuracy. The errors shown in Fig.~\ref{tunnel_demo_fig} are relatively large because fires in long, closed enclosures like tunnels can generate large fluctuations in pressure that challenge both the multiple mesh capability and the pressure solving algorithm discussed above.

\begin{figure}[ht]
\includegraphics[width=3in]{SCRIPT_FIGURES/tunnel_demo_velocity}
\includegraphics[width=3in]{SCRIPT_FIGURES/tunnel_demo_pressure}
\caption[Convergence test for the {\ct tunnel\_demo} test case]{Reduction in velocity and pressure error due to iteration of the pressure solver.}
\label{tunnel_demo_fig}
\end{figure}

\subsubsection{Special Case: Pressure Drop in Long Tunnels}
\label{sec:tunnel_pressure_drop}

In this section, we develop a set of cases to extract the implied friction factor from an FDS simulation of flow down a long tunnel ({\ct Validation/Moody\_Chart/FDS\_Input\_Files/tunnel\_pressure\_drop} series).  Note that a more complete mapping of the Moody Chart is provided in the FDS Verification Guide \cite{FDS_Verification_Guide}, but that series uses a mean pressure gradient to force the flow, which is not a typical user case.  Here we force the flow from a {\ct VENT} and we monitor the pressure using planar averaged {\ct DEVC}s.  The tunnel is 1.6 km (approximately one mile) long with a square cross-section 10 m $\times$ 10 m for Cases A, B, C, and D.  The cross section for Case E is 12.8 m (width) $\times$ 5 m (height), giving a hydraulic diameter of 7.2 m. We push air from the entrance at 2, 4, or 10 m/s for sand-grain roughness heights of 0.0001, 0.01, or 0.1 m.  We run two grid resolutions with uniform cells in the vertical direction corresponding to 10 and 20 cells across the tunnel height.  Streamwise grid resolution is twice the wall-normal resolution.  The case matrix and friction factor results are given in Table~\ref{tab:tunnel_pressure_drop}.  The target friction factor is taken from the Colebrook equation (see \cite{MYO}).  FDS results for the 10 and 20 resolution cases are also shown along with the max relative error as compared to the Colebrook value. The pressure profiles are shown in Fig.~\ref{fig:tunnel_pressure_drop}.

\begin{table}[ht]
\input{SCRIPT_FIGURES/tunnel_pressure_drop}
\end{table}

\begin{figure}[ht]
\centering
\includegraphics[width=3in]{SCRIPT_FIGURES/tunnel_pressure_drop_a}
\includegraphics[width=3in]{SCRIPT_FIGURES/tunnel_pressure_drop_b}\\
\includegraphics[width=3in]{SCRIPT_FIGURES/tunnel_pressure_drop_c}
\includegraphics[width=3in]{SCRIPT_FIGURES/tunnel_pressure_drop_d}\\
\includegraphics[width=3in]{SCRIPT_FIGURES/tunnel_pressure_drop_e}
\caption[The {\ct tunnel\_pressure\_drop} cases]{Tunnel pressure drop for cases listed in Table \ref{tab:tunnel_pressure_drop}.}
\label{fig:tunnel_pressure_drop}
\end{figure}

A word of caution: To achieve sensible results for tunnel cases you must take care to eliminate any mesh-to-mesh mass conservation errors and you must ensure that the time step stability criterion is never violated.  For the first, you should simply use the {\ct 'GLMAT'} solver.  To remain stable, use {\ct CFL\_VELOCITY\_NORM=1}, which employs a more restrictive definition of the cell velocity magnitude.  Without this setting, even slight violations of the stability limits (which are precisely unknown for the Navier-Stokes equations, in general) may lead to dramatic spurious pressure oscillations.  We also find that improved results for friction factor are obtained if the {\ct 'WALE'} near-wall eddy-viscosity is used.  Both these settings can be achieved using {\ct 'LES'} mode.

\begin{lstlisting}
&MISC SIMULATION_MODE='LES'/
&PRES SOLVER='GLMAT'/
\end{lstlisting}

While reasonable grid resolution is important, as you can see, the wall models in FDS are capable of giving the correct mean wall stress even at rather coarse resolution.  For example, the $y^+$ for Case C with 10 cells is, in fact, 5000 (this is the location of the middle of the first grid cell divided by the roughness height).  Note that this resolution may not be sufficient if other complexities exist and it is the user's responsibility to ensure grid convergence for their application.

Also, note that a roughness of 0.1 mm is used here only for completeness in testing the code.  While this is indeed the value one finds in the literature for the roughness of concrete, a real-world tunnel may have geometric features along the walls that are unresolved by the grid and may act as roughness elements.  These elements should be considered when specifying the roughness in FDS.


\section{Breaking Pressure Zones}
\label{background_pressure}

There are two parameters on the {\ct PRES} line that control iterative procedures related to the coupling of velocity and pressure. One is
called {\ct RELAXATION\_FACTOR} and its default value is 1. When there is an error in the normal component of velocity at a solid boundary, this
parameter dictates that the correction be applied in 1 time step. If its value were 0.5, the correction would be applied in 2 time steps.

A similar parameter is the {\ct PRESSURE\_RELAX\_TIME}. It controls the rate at which the pressures in adjacent compartments are brought into equilibrium following a
breach. Its default value is 1~s, meaning that equilibrium is achieved in roughly a second.











\chapter{Building the Model}

A considerable amount of work in setting up a calculation lies in specifying the
geometry of the space to be modeled and applying boundary conditions
to the solid surfaces. The geometry is described in terms
of rectangular obstructions that can heat up, burn, conduct heat, etc.;
and vents from which air or fuel can be
either injected into, or drawn from, the flow domain.
A boundary condition needs to be assigned to each obstruction
and vent describing its thermal properties. A fire is just one type of
boundary condition. This chapter describes how to build the model.


\section{Bounding Surfaces: The \texorpdfstring{{\tt SURF}}{SURF} Namelist Group (Table \ref{tbl:SURF})}
\label{info:SURF}

Before describing how to build up the geometry, it is first necessary to explain how to describe what these bounding surfaces
consist of. {\ct SURF} is the namelist group that defines
the structure of all solid surfaces or openings within or
bounding the flow domain. Boundary conditions for obstructions and vents are
prescribed by referencing the appropriate {\ct SURF} line(s) whose
parameters are described in this section.

The default boundary condition for all solid surfaces is that of a smooth
inert wall with the surface temperature fixed at {\ct TMPA}, and is referred to as {\ct 'INERT'}. Do not confuse this with a surface for which heat transfer does not occur (this is an adiabatic surface which will change in temperature to maintain zero heat transfer, refer to Section~\ref{info:adiabatic}). To maintain the surface temperature at {\ct TMPA} when exposed to a gas temperature, which may be above or below {\ct TMPA}, FDS calculates the required heat transfer coefficient, and hence the heat transfer between the surface and the gas phase. You can think of {\ct INERT} as the ultimate ambient temperature heat sink; such as a water-cooled panel.

If only this boundary condition is needed, there is no need to add any {\ct SURF} lines
to the input file. If additional boundary conditions are desired,
they are to be listed one boundary condition at a time.
Each {\ct SURF} line consists of an identification string {\ct ID='...'} to
allow references to it by an obstruction or vent. Thus, on each
{\ct OBST} and {\ct VENT} line that are to be described below, the character string {\ct SURF\_ID='...'}
indicates the {\ct ID} of the {\ct SURF} line containing the desired boundary
condition parameters. If a particular {\ct SURF} line is to be applied
as the default boundary condition,
set {\ct DEFAULT=.TRUE.} on the {\ct SURF} line.




\section{Creating Obstructions: The \texorpdfstring{{\tt OBST}}{OBST} Namelist Group (Table \ref{tbl:OBST})}
\label{info:OBST}

The namelist group {\ct OBST} contains parameters used to define obstructions. The entire geometry of the model is made up entirely of rectangular solids, each one introduced on a single line in the input file.

\subsection{Basics}
\label{info:OBST_Basics}

Each {\ct OBST} line contains the coordinates of a rectangular
solid within the flow domain. This solid is defined by two points
($x_1$,$y_1$,$z_1$) and ($x_2$,$y_2$,$z_2$) that are entered on the
{\ct OBST} line in terms of the real sextuplet {\ct XB}.
In addition to the coordinates, the boundary conditions for the obstruction
can be specified with the parameter {\ct SURF\_ID}, which designates which
{\ct SURF} line (Section~\ref{info:SURF}) to apply at the surface of the obstruction.
If the obstruction has different properties for its top,
sides and bottom, do not specify only one {\ct SURF\_ID}. Instead, use {\ct SURF\_IDS}, an array of three character
strings specifying the boundary condition {\ct ID}s for the top,
sides and bottom of the obstruction, respectively.
If the default
boundary condition is desired, then {\ct SURF\_ID} or {\ct SURF\_IDS} need not be set.
However, if at least one of the surface conditions for an
obstruction is the inert default, it can be referred to as {\ct 'INERT'}, but it does not have to be explicitly defined.
For example:
\begin{lstlisting}
&SURF ID='FIRE', HRRPUA=1000.0 /
&OBST XB=2.3,4.5,1.3,4.8,0.0,9.2, SURF_IDS='FIRE','INERT','INERT' /
\end{lstlisting}
puts a fire on top of the obstruction. This is a simple way of
prescribing a burner.

In addition to {\ct SURF\_ID} and {\ct SURF\_IDS}, you can also use the sextuplet {\ct SURF\_ID6} as follows:
\begin{lstlisting}
&OBST XB=2.3,4.5,1.3,4.8,0.0,9.2,
      SURF_ID6='FIRE','INERT','HOT','COLD','BLOW','INERT' /
\end{lstlisting}
where the six surface descriptors refer to the planes $x=2.3$, $x=4.5$, $y=1.3$, $y=4.8$, $z=0.0$, and $z=9.2$, respectively. Note that {\ct SURF\_ID6} should not be used on the same {\ct OBST} line as {\ct SURF\_ID} or {\ct SURF\_IDS}.

Obstructions may be created or removed during a simulation. See Section~\ref{info:create_remove} for details.


\subsection{Thin Obstructions}

Obstructions can have zero thickness. Often, thin sheets, like a window, form a barrier, but if the numerical mesh is coarse relative to the thickness of the barrier, the obstruction might be unnecessarily large if it is assumed to be one layer of mesh cells thick. All faces of an obstruction are shifted to the closest mesh cell. If the obstruction is very thin, the two faces may be approximated on the same cell face. FDS and Smokeview render this obstruction as a thin sheet, but it is allowed to have thermally thick boundary conditions. This feature is fragile, especially in terms of burning and blowing gas. A thin sheet obstruction can only have one velocity vector on its face, thus a gas cannot be injected reliably from a thin obstruction because whatever is pushed from one side is necessarily pulled from the other. For full functionality, the obstruction should be specified to be at least one mesh cell thick. Thin sheet obstructions work fine as flow barriers, but other features are fragile and should be used with caution. To prevent FDS from allowing thin sheet obstructions, set {\ct THICKEN\_OBSTRUCTIONS=.TRUE.} on the {\ct MISC} line, or {\ct THICKEN=.TRUE.} on each {\ct OBST} line for which the thin sheet assumption is not allowed.

Obstructions that are too small relative to the underlying numerical mesh are rejected. Be careful when testing cases on coarse meshes.

\subsection{Overlapping Obstructions}

If the faces of two obstructions overlap each other, FDS will choose the surface properties of the obstruction that is specified second in the input file. If you do not want this, add {\ct OVERLAY=.FALSE.} to the {\ct OBST} line of the second obstruction, in which case the surface properties of the first obstruction will be applied. The default value of {\ct OVERLAY} is {\ct .TRUE.}

When obstructions overlap, Smokeview renders both obstructions independently of each other, often leading to an unsightly cross-hatching of the two surface colors where there is an overlap. A simple remedy for this is to ``shrink'' the obstruction you do not wish to take precedence by slightly by adjusting its coordinates ({\ct XB}) accordingly. Then, in Smokeview, toggle the ``q'' key to show the obstructions as you specified them, rather than as FDS rendered them.

\subsection{Preventing Obstruction Removal}

Obstructions can be protected from the {\ct HOLE} punching feature. Sometimes it is convenient to create a door or window using a {\ct HOLE}. For example, suppose a {\ct HOLE} is punched in a wall to represent a door or window. An obstruction can be defined to fill this hole (presumably to be removed or colored differently or whatever) so long as the phrase {\ct PERMIT\_HOLE=.FALSE.} is included on the {\ct OBST} line. In general, any obstruction can be made impenetrable to a {\ct HOLE} using this phrase. By default, {\ct PERMIT\_HOLE=.TRUE.}, meaning that an obstruction is assumed to be penetrable unless otherwise directed. Note that if a penetrable  obstruction and an impenetrable  obstruction overlap, the obstruction with {\ct PERMIT\_HOLE=.FALSE.} should be listed first.

If the obstruction is not to be removed or rejected for any reason, set {\ct REMOVABLE=.FALSE.} This is sometimes needed to stop
FDS from removing the obstruction if it is embedded within another, like a door within a wall.

In rare cases, you might not want to allow a {\ct VENT} to be attached to a particular obstruction, in which case set {\ct ALLOW\_VENT=.FALSE.}

\subsection{Transparent or Outlined Obstructions}

Obstructions can be made semi-transparent by assigning a {\ct TRANSPARENCY} on the {\ct OBST} line. This real parameter ranges from 0 to 1, with 0 being fully transparent. The parameter should always be set along with either {\ct COLOR} or an {\ct RGB} triplet. It can also be specified on the appropriate {\ct SURF} line, along with a color indicator. If you want the obstruction to be invisible, set {\ct COLOR='INVISIBLE'}.

Obstructions are typically drawn as solids in Smokeview. To draw an outline representation, set {\ct OUTLINE} equal to {\ct .TRUE.}



\subsection{Creating Holes in Obstructions: The \texorpdfstring{{\tt HOLE}}{HOLE} Namelist Group (Table \ref{tbl:HOLE})}
\label{info:HOLE}

The {\ct HOLE} namelist group defines parameters that carve a hole out of an existing obstruction or set of obstructions. To do this, add lines of the form
\begin{lstlisting}
&HOLE XB=2.0,4.5,1.9,4.8,0.0,9.2 /
\end{lstlisting}
Any solid mesh cells within the volume $2.0<x<4.5$, $1.9<y<4.8$, $0.0<z<9.2$ are removed. Obstructions intersecting the volume are broken up into smaller blocks. If the hole represents a door or window, a good rule of thumb is to punch more than enough to create the hole. This ensures that the hole is created through the entire obstruction. For example, if the {\ct OBST} line denotes a wall 0.1~m thick:
\begin{lstlisting}
&OBST XB=1.0,1.1,0.0,5.0,0.0,3.0 /
\end{lstlisting}
and you want to create a door, add this:
\begin{lstlisting}
&HOLE XB=0.99,1.11,2.0,3.0,0.0,2.0 /
\end{lstlisting}
The extra centimeter added to the $x$ coordinates of the hole make it clear that the hole is to punch through the entire obstruction.

When a {\ct HOLE} is created, the affected obstruction(s) are either rejected, or created or removed at pre-determined times. See Section~\ref{info:create_remove} for details. To allow a hole to be controlled with either the {\ct CTRL} or {\ct DEVC} namelist groups, you will need to add the {\ct CTRL\_ID} or {\ct DEVC\_ID} parameter respectively, to the {\ct HOLE} line\footnote{If you add a {\ct CTRL\_ID} or {\ct DEVC\_ID} to the {\ct HOLE} line, do not overlap this {\ct HOLE} with another. The control logic can fail.}.   When the state of the {\ct HOLE} evaluates to {\ct .FALSE.}, an obstruction will be placed in the {\ct HOLE}.  By default the obstruction filling the {\ct HOLE} will take the color of the surrounding {\ct OBST} that the {\ct HOLE} was punched through.  To make the obstruction filling the {\ct HOLE} a different color than the original obstruction, set the {\ct COLOR} or integer triplet {\ct RGB} on the {\ct HOLE} line (see Section~\ref{info:colors}). If you want the obstruction filling the {\ct HOLE} to be invisible, then set {\ct COLOR='INVISIBLE'}.  Additionally, you may use the keyword {\ct TRANSPARENCY}, real number from 0 to 1, to make the obstruction filling the {\ct HOLE} transparent. See Section~\ref{info:create_remove} for an example.

If an obstruction is not to be punctured by a {\ct HOLE}, add {\ct PERMIT\_HOLE=.FALSE.} to the {\ct OBST} line. Note that a {\ct HOLE} has no effect on a {\ct VENT} or a mesh boundary. It only applies to {\ct OBST}ructions.

It is a good idea to inspect the geometry by running either a setup job
({\ct T\_END=0} on the {\ct TIME} line) or a short-time job to test the operation of devices and control functions.



\section{Applying Surface Properties: The \texorpdfstring{{\tt VENT}}{VENT} Namelist Group (Table \ref{tbl:VENT})}
\label{info:VENT}

Whereas the {\ct OBST} group is used to specify obstructions within the
computational domain, the {\ct VENT} group (Table \ref{tbl:VENT}) is used to prescribe planes
adjacent to obstructions or external walls. Note that the label {\ct VENT} is used for historical reasons -- this group of parameters has
evolved well beyond its initial role as simply allowing for air to be blown into, or sucked out of, the computational domain.

\subsection{Basics}

\label{info:VENT_Basics}

The vents are chosen in a similar manner to the obstructions, with the sextuplet {\ct XB} denoting a plane abutting a solid surface. Two of the six coordinates must be the same, denoting a plane as opposed to a solid. Note that only one {\ct VENT} may be specified for any given wall cell.  If additional {\ct VENT} lines are specified for a given wall cell, FDS will output a warning message and ignore redundant {\ct VENT} lines.

The term ``{\ct VENT}'' is somewhat misleading. Taken literally, a
{\ct VENT} can be used to model components of the ventilation system in
a building, like a diffuser or a return.
In these cases, the {\ct VENT} coordinates form a plane on a
solid surface forming the boundary of the duct.
No holes need to be created through the solid; it is
assumed that air is pushed out of or sucked into duct work within the
wall. Less literally, a {\ct VENT} is used simply as a means of applying
a particular boundary condition to a rectangular patch on a solid surface.
A fire, for example, is usually created by first generating a solid
obstruction via an {\ct OBST} line, and then specifying a {\ct VENT}
somewhere on one of the faces of the solid with a {\ct SURF\_ID}
with the characteristics of the thermal and combustion properties of the fuel.
For example, the lines

\begin{lstlisting}
&OBST XB=0.0,5.0,2.0,3.0,0.0,4.0, SURF_ID='big block' /
&VENT XB=1.0,2.0,2.0,2.0,1.0,3.0, SURF_ID='hot patch' /
\end{lstlisting}

\noindent
specify a large obstruction (with the properties given elsewhere in the file under the name {\ct 'big block'}) with
a ``patch'' applied to one of its faces with alternative properties under the name {\ct 'hot patch'}. This latter
surface property need not actually be a ``vent,'' like a supply or return duct, but rather just a patch with different boundary
conditions than those assumed for the obstruction. Note that the surface properties of a {\ct VENT} over-ride those of the
underlying obstruction.

A {\ct VENT} must always be attached to a solid obstruction. See
Section~\ref{info:Velocity_BC} for instructions on specifying different types of fans that allow gases to flow through.

An easy way to specify an entire external wall is to replace {\ct XB} with
{\ct MB} (Mesh Boundary), a character string whose value is one of the following:
{\ct 'XMAX'}, {\ct 'XMIN'}, {\ct 'YMAX'}, {\ct 'YMIN'}, {\ct 'ZMAX'} or
{\ct 'ZMIN'} denoting the planes $x=\hbox{\ct XMAX}$, $x=\hbox{\ct XMIN}$,
$y=\hbox{\ct YMAX}$, $y=\hbox{\ct YMIN}$, $z=\hbox{\ct ZMAX}$
or $z=\hbox{\ct ZMIN}$, respectively.
Like an obstruction, the boundary condition index of a vent is specified
with {\ct SURF\_ID}, indicating which of the listed {\ct SURF} lines to
apply. If the default boundary condition is desired, then {\ct SURF\_ID} need not be set.

Be careful when using the {\ct MB} shortcut when doing a multiple mesh
simulation; that is, when more than one rectangular mesh is used. The
plane designated by the character string {\ct MB} may be mistakenly applied to more than one
mesh, possibly leading to confusion about whether a plane is a solid
wall or an open boundary. Check the geometry in Smokeview to assure that
the {\ct VENT}s are properly specified. Use color as much as
possible to double-check the set-up.  More detail on color in
Section~\ref{info:colors} and Table \ref{tab:colors}. Also, the parameter {\ct OUTLINE=.TRUE.} on the {\ct VENT} line causes the {\ct VENT} to be drawn as an outline in Smokeview.


\subsection{Special Vents}

\label{info:Special_VENTS}

There are four reserved {\ct SURF\_ID}'s that may be applied to a {\ct VENT} -- {\ct 'OPEN'}, {\ct 'MIRROR'}, {\ct 'PERIODIC'}, and {\ct HVAC}. The term {\em reserved} means that these {\ct SURF\_ID}s should not be explicitly defined by you. Their properties are predefined.

\subsubsection{Open Vents}

The first special {\ct VENT} is invoked by the parameter {\ct SURF\_ID='OPEN'}. This is used only if the {\ct VENT} is applied to the exterior boundary of the computational domain, where it denotes a passive opening to the outside. By default, FDS assumes that the exterior boundary of the computational domain (the {\ct XB}s on the {\ct MESH} line) is a solid wall. To create a totally or partially open domain, use {\ct OPEN} vents on the exterior mesh boundaries. It is sometimes convenient to specify doors or windows that open out to the exterior of the computational domain by simply specifying it to be {\ct OPEN}. However, keep in mind that the pressure boundary condition on such an opening is imperfect, and it is recommended that if the flow through the doorway or window is important, you should extend the domain a few meters rather than use an {\ct OPEN} boundary. You would still have to use the {\ct OPEN} boundary to open up one or more sides of the computational domain, but these openings would be far enough away from the modeled door or window that they would not affect the flow pattern.

By default, it is assumed that ambient conditions exist beyond the {\ct 'OPEN'} vent. However, in some cases, you may want to alter this assumption, for example, the temperature. If you assume a temperature other than ambient, specify {\ct TMP\_EXTERIOR} along with {\ct SURF\_ID='OPEN'}. You can modify the time history of this parameter using a ramp function, {\ct TMP\_EXTERIOR\_RAMP}. Use this option cautiously -- in many situations if you want to describe the exterior of a building, it is better to include the exterior explicitly in your calculation because the flow in and out of the doors and windows will be more naturally captured. See Section~\ref{info:stackeffect} for more details. If you want to specify a non-ambient pressure at the {\ct OPEN} boundary, see Section~\ref{info:pressure_boundary}.

The {\ct OPEN} pressure boundary condition is most stable for flows that are predominantly normal  to the vent, either mostly in or mostly out.  This is because the prescribed pressure at an {\ct OPEN} boundary is ill-conditioned (a small perturbation to the input may lead to large change in the output) if the flow is parallel to the vent.  Suppose, for example, that an outdoor flow is 10 m/s in the $x$ direction and $\pm 0.001$ m/s in the $z$ direction with an {\ct OPEN} top boundary.  The kinetic energy of this flow is roughly $k=50$ m$^2$/s$^2$.  When the vertical velocity is positive (+0.001 m/s) then the prescribed boundary condition for the stagnation pressure is set to $\cH = k = 50$ m$^2$/s$^2$.  But when the vertical velocity is negative (-0.001 m/s) then $\cH = 0$ (see \cite{FDS_Tech_Guide}).  For this reason, {\ct OPEN} vents should be used with care in outdoor applications.  See Section \ref{info:WIND} for an alternative approach.


Vents to the outside of the computational domain ({\ct OPEN} vents)
{\em  can} be opened or closed during a simulation. It is best done by creating or removing a thin obstruction that covers the {\ct OPEN VENT}.
See Section~\ref{info:activate_deactivate} for details.


\subsubsection{Mirror Vents}

A {\ct VENT} with {\ct SURF\_ID='MIRROR'} denotes a symmetry plane. Usually, a {\ct MIRROR} spans an entire face of the computational domain, essentially doubling the size of the domain with the {\ct MIRROR} acting as a plane of symmetry. The flow on the opposite side of the {\ct MIRROR} is exactly reversed\footnote{Note that the mirror image of a scene is {\em not} shown in Smokeview.}. From a numerical point of view, a {\ct MIRROR} is a no-flux, free-slip boundary. As with {\ct OPEN}, a {\ct MIRROR} can only be prescribed at an exterior boundary of the computational domain. Often, {\ct OPEN} or {\ct MIRROR} {\ct VENT}s are prescribed along an entire side of the computational domain, in which case the ``{\ct MB}'' notation is handy.

In conventional RANS (Reynolds-Averaged Navier-Stokes) models, symmetry boundaries are often used as a way of saving on computation time. However, because FDS is an LES (Large Eddy Simulation) model, the use of symmetry boundaries should be considered carefully. The reason for this is that an LES model does not compute a time-averaged solution of the N-S equations. In other words, for a RANS model, a fire plume is represented as an axially-symmetric flow field because that is what you would expect if you time-averaged the actual flow field over a sufficient amount of time. Thus, for a RANS model, a symmetry boundary along the plume centerline is appropriate. In an LES model, however, there is no time-averaging built into the equations, and there is no time-averaged, symmetric solution. Putting a {\ct MIRROR} boundary along the centerline of a fire plume will change its dynamics entirely. It will produce something very much like the flow field of a fire that is adjacent to a vertical wall. For this reason, a {\ct MIRROR} boundary condition is not recommended along the centerline of a turbulent fire plume. If the fire or burner is very small, and the flow is laminar, then the {\ct MIRROR} boundary condition makes sense. In fact, in 2-D calculations, {\ct MIRROR} boundary conditions are employed in the third coordinate direction (this is done automatically, you need not specify it explicitly).

\subsubsection{Periodic Vents}
\label{sec:periodic}

A {\ct VENT} with {\ct SURF\_ID='PERIODIC'} may be used in combination with another periodic vent on the opposite side of the domain.  If the domain consists of only a single mesh, the lines:
\begin{lstlisting}
&VENT MB='XMIN', SURF_ID='PERIODIC' /
&VENT MB='XMAX', SURF_ID='PERIODIC' /
\end{lstlisting}
designate that the simulation is periodic in the $x$-direction. For multi-mesh domains where {\ct PERIODIC} boundary conditions are applied, the entire domain must be a single large block and the {\ct VENT} planes must be specified using {\ct PBX}, {\ct PBY}, or {\ct PBZ}.  If $x_{\si{min}}=0$ and $x_{\si{max}}=1$, for example, use
\begin{lstlisting}
&VENT PBX=0, SURF_ID='PERIODIC' /
&VENT PBX=1, SURF_ID='PERIODIC' /
\end{lstlisting}
For additional information related to periodic boundaries and the pressure solver see Section~\ref{sec:true_periodic_boundaries}.

Periodic vents may not be used to connect offset vents or vents in different coordinate directions.  For such cases, you must employ HVAC capabilities (see Section~\ref{info:HVAC}).

Note that, by default, particles are not recycled at periodic boundaries.  See Section~\ref{info:periodic-particles} if periodic particles are desired.

\subsubsection{HVAC Vents}

A {\ct VENT} with {\ct SURF\_ID='HVAC'} denotes that the vent is connected to an HVAC system. See Section~\ref{info:HVAC} for a description of inputs for HVAC systems.

\subsubsection{Circular Vents}
\label{sec:circvents}
\label{circular_burner}

Circular or semi-circular vents may be specified as the intersection of a rectangle with coordinates {\ct XB} and a circle with center {\ct XYZ} and radius {\ct RADIUS}.  The rectangular surface cells that are assigned the corresponding {\ct SURF\_ID} will be those whose centroid falls within the intersection. In the example case called {\ct Fires/circular\_burner.fds}, the following two lines create a circular vent that is 1~m in diameter and flows propane gas at a rate of 0.02~kg/m$^2$/s:
\begin{lstlisting}
&SURF ID='BURNER', MASS_FLUX(1)=0.02, SPEC_ID(1)='PROPANE', TAU_MF(1)=0.01 /
&VENT XB=-0.6,0.6,-0.6,0.6,0,0, XYZ=0,0,0, RADIUS=0.5, SURF_ID='BURNER',
      SPREAD_RATE=0.05 /
\end{lstlisting}
The {\ct XB} coordinates designate the orientation of the vent. In this case, the extent of the area specified by {\ct XB} is large enough to contain the entire circle. Note also in this example that the parameter {\ct SPREAD\_RATE} causes the fire to spread outward at a rate of 0.05~m/s. The mass flux of propane through the vent is plotted in Fig.~\ref{circ_burn}. Notice that the mass flux increases following a ``t-squared'' profile. This is what is expected of a fire which spreads radially at a linear rate. In this case, the fire reaches the {\ct RADIUS} of the circle in 10~s, as expected. Note also that the parameter {\ct TAU\_MF} indicates that the fuel should ramp up quickly once the flame front reaches a given grid cell. In other words, {\ct TAU\_MF} controls the local ramp-up of fuel; the {\ct SPREAD\_RATE} controls the global ramp-up. Following the ramp-up, the fuel flows at a rate equal to the area of the circle times the mass flux of fuel per unit area. Even if the circle is crudely resolved on a coarse grid, the fuel flow rate will be adjusted to produce the desired value governed by the circular vent.
\begin{figure}[h]
\begin{center}
\includegraphics[width=3in]{SCRIPT_FIGURES/circular_burner}
\caption[Results of the {\ct circular\_burner} test case]{Results of the {\ct circular\_burner} test case.}
\label{circ_burn}
\end{center}
\end{figure}


\subsection{Controlling Vents}

{\ct VENT} functionality can be controlled in some cases using ``devices'' and ``controls,'' specified via a {\ct DEVC\_ID} or a {\ct CTRL\_ID}.
See Section~\ref{info:activate_deactivate} for details.

\subsection{Trouble-Shooting Vents}
\label{info:VENT_Trouble}

Unlike most of the entries in the input file, the order that you specify {\ct VENT}s can be important. There might be
situations where it is convenient to position one {\ct VENT} atop another. For example, suppose you want to designate the
ceiling of a compartment to have a particular set of surface properties, and you designate the entire ceiling to have the
appropriate {\ct SURF\_ID}. Then, you want to designate a smaller patch on the ceiling to have another set of surface
properties, like an air supply. In this case, you must designate the supply {\ct VENT} {\em first} because for that area
of the ceiling, FDS will ignore the ceiling properties and apply the supply properties. FDS processes the first {\ct VENT}, not
the second as it did in versions prior to FDS 5. Now, the rule for {\ct VENT}s is ``first come, first served.''
Keep in mind, however, that the
second {\ct VENT} is not rejected entirely -- only where there is overlap. FDS will also print out a warning to the screen (or to
standard error) saying which {\ct VENT} has priority.  Also, be careful if any of the {\ct VENT}s are applying {\ct OPEN} boundary conditions -- {\ct OPEN} boundaries disable pressure {\ct ZONE}s, which will change the solutio of the problem.

Smokeview can help identify where two {\ct VENT}s overlap, assuming each has a unique {\ct COLOR}. Because Smokeview draws {\ct VENT}s
on top of each other, areas of overlap will have a grainy, awkward appearance that changes pattern as you move the scene. In situations
where you desire the overlap for the sake of convenience, you might want to slightly adjust the coordinates of the preferred {\ct VENT}
so that it is slightly offset from the solid surface. Make the offset less than about a tenth of a cell dimension so that FDS snaps it
to its desired location. Then, by toggling the ``q'' key in Smokeview, you can eliminate the grainy color overlap by showing the
{\ct VENT} exactly where you specified it, as opposed to where FDS repositioned it. This trick also works where the faces of two
obstructions overlap.

If an error message appears requesting that
the orientation of a vent be specified, first check to make sure that the vent is a plane.
If the vent is a plane, then the orientation can be forced by specifying the parameter {\ct IOR}.
If the normal direction of the {\ct VENT} is in the positive $x$ direction, set {\ct IOR=1}.
If the normal direction is in the negative $x$ direction, set {\ct IOR=-1}. For the $y$ and
$z$ direction, use the number 2 and 3, respectively. Setting {\ct IOR} may sometimes solve
the problem, but it is more likely that if there is an error message about orientation, then
the {\ct VENT} is buried within a solid obstruction, in which case the program cannot determine
the direction in which the {\ct VENT} is facing.



\section{Coloring Obstructions, Vents, Surfaces and Meshes}
\label{info:colors}

It is useful when visualizing the results of a simulation to assign to objects a meaningful color or pattern. There are two ways to do this in FDS. You can either assign a single color, or you can assign a texture map, which is essentially an image of a your choosing.

\subsection{Colors}

Colors for many items within FDS can be prescribed in two ways; a triplet of integer color values, {\ct RGB}, or a character string, {\ct COLOR}. The three {\ct RGB} integers range from 0 to 255, indicating the amount of Red, Green and Blue that make up the color. If you define the {\ct COLOR} by name, it is important that you type the name {\em exactly} as it is listed in the color tables. Color parameters can be specified on a {\ct SURF} line, in which case all surfaces of that type will have that color, or color parameters can be applied directly to obstructions or vents. For example, the lines:
\begin{lstlisting}
&SURF ID='UPHOLSTERY', ..., RGB=0,255,0 /
&OBST XB=..., COLOR='BLUE' /
\end{lstlisting}
will color all {\ct UPHOLSTERY} green and this particular obstruction blue. Table~\ref{tab:colors} provides a small sampling of {\ct RGB} values and {\ct COLOR} names for a variety of colors\footnote{A complete listing of all 500+ colors can be found by searching the FDS source code file {\ct data.f90}.}.
It is highly recommended that colors be assigned to surfaces via the {\ct SURF} line. As the geometries of FDS simulations become more complex, it is very useful to use color as a spot check to determine if the desired surface properties have been assigned throughout the geometry.

Obstructions and vents may be colored individually, over-riding the color designated by the {\ct SURF} line. The special case {\ct COLOR='INVISIBLE'} causes the vent or obstruction not to be drawn by Smokeview. Another special case {\ct COLOR='RAINBOW'} causes the color of the vent, obstruction or mesh to be randomly selected from the full range of RGB values; this can be useful if you are using the {\ct MULT} namelist group and want to differentiate between the multiplied obstruction, vent or mesh.


\begin{table}[p]
\begin{center}
\caption[A sample of color definitions]{A sample of color definitions.}
\label{tab:colors}
\vspace{0.1in}
\begin{tabular}{|c|c|c|c|c|c||c|c|c|c|}
\hline
Name & &  R  & G & B & Name & & R & G & B   \\ \hline \hline
{\ct AQUAMARINE} & \textcolor{AQUAMARINE} {$\blacksquare$} & 127& 255& 212& {\ct MAROON} &  \textcolor{MAROON} {$\blacksquare$} & 128& 0& 0  \\ \hline
{\ct ANTIQUE WHITE} & \textcolor{ANTIQUE WHITE} {$\blacksquare$} & 250& 235& 215& {\ct MELON} &  \textcolor{MELON} {$\blacksquare$} & 227& 168& 105  \\ \hline
{\ct BEIGE} & \textcolor{BEIGE} {$\blacksquare$} & 245& 245& 220& {\ct MIDNIGHT BLUE} &  \textcolor{MIDNIGHT BLUE} {$\blacksquare$} & 25& 25& 112  \\ \hline
{\ct BLACK} & \textcolor{BLACK} {$\blacksquare$} & 0& 0& 0& {\ct MINT} &  \textcolor{MINT} {$\blacksquare$} & 189& 252& 201  \\ \hline
{\ct BLUE} & \textcolor{BLUE} {$\blacksquare$} & 0& 0& 255& {\ct NAVY} &  \textcolor{NAVY} {$\blacksquare$} & 0& 0& 128  \\ \hline
{\ct BLUE VIOLET} & \textcolor{BLUE VIOLET} {$\blacksquare$} & 138& 43& 226& {\ct OLIVE} &  \textcolor{OLIVE} {$\blacksquare$} & 128& 128& 0  \\ \hline
{\ct BRICK} & \textcolor{BRICK} {$\blacksquare$} & 156& 102& 31& {\ct OLIVE DRAB} &  \textcolor{OLIVE DRAB} {$\blacksquare$} & 107& 142& 35  \\ \hline
{\ct BROWN} & \textcolor{BROWN} {$\blacksquare$} & 165& 42& 42& {\ct ORANGE} &  \textcolor{ORANGE} {$\blacksquare$} & 255& 128& 0  \\ \hline
{\ct BURNT SIENNA} & \textcolor{BURNT SIENNA} {$\blacksquare$} & 138& 54& 15& {\ct ORANGE RED} &  \textcolor{ORANGE RED} {$\blacksquare$} & 255& 69& 0  \\ \hline
{\ct BURNT UMBER} & \textcolor{BURNT UMBER} {$\blacksquare$} & 138& 51& 36& {\ct ORCHID} &  \textcolor{ORCHID} {$\blacksquare$} & 218& 112& 214  \\ \hline
{\ct CADET BLUE} & \textcolor{CADET BLUE} {$\blacksquare$} & 95& 158& 160& {\ct PINK} &  \textcolor{PINK} {$\blacksquare$} & 255& 192& 203  \\ \hline
{\ct CHOCOLATE} & \textcolor{CHOCOLATE} {$\blacksquare$} & 210& 105& 30& {\ct POWDER BLUE} &  \textcolor{POWDER BLUE} {$\blacksquare$} & 176& 224& 230  \\ \hline
{\ct COBALT} & \textcolor{COBALT} {$\blacksquare$} & 61& 89& 171& {\ct PURPLE} &  \textcolor{PURPLE} {$\blacksquare$} & 128& 0& 128  \\ \hline
{\ct CORAL} & \textcolor{CORAL} {$\blacksquare$} & 255& 127& 80& {\ct RASPBERRY} &  \textcolor{RASPBERRY} {$\blacksquare$} & 135& 38& 87  \\ \hline
{\ct CYAN} & \textcolor{CYAN} {$\blacksquare$} & 0& 255& 255& {\ct RED} &  \textcolor{RED} {$\blacksquare$} & 255& 0& 0  \\ \hline
{\ct DIM GRAY } & \textcolor{DIM GRAY } {$\blacksquare$} & 105& 105& 105& {\ct ROYAL BLUE} &  \textcolor{ROYAL BLUE} {$\blacksquare$} & 65& 105& 225  \\ \hline
{\ct EMERALD GREEN} & \textcolor{EMERALD GREEN} {$\blacksquare$} & 0& 201& 87& {\ct SALMON} &  \textcolor{SALMON} {$\blacksquare$} & 250& 128& 114  \\ \hline
{\ct FIREBRICK} & \textcolor{FIREBRICK} {$\blacksquare$} & 178& 34& 34& {\ct SANDY BROWN} &  \textcolor{SANDY BROWN} {$\blacksquare$} & 244& 164& 96  \\ \hline
{\ct FLESH} & \textcolor{FLESH} {$\blacksquare$} & 255& 125& 64& {\ct SEA GREEN} &  \textcolor{SEA GREEN} {$\blacksquare$} & 84& 255& 159  \\ \hline
{\ct FOREST GREEN} & \textcolor{FOREST GREEN} {$\blacksquare$} & 34& 139& 34& {\ct SEPIA} &  \textcolor{SEPIA} {$\blacksquare$} & 94& 38& 18  \\ \hline
{\ct GOLD } & \textcolor{GOLD } {$\blacksquare$} & 255& 215& 0& {\ct SIENNA} &  \textcolor{SIENNA} {$\blacksquare$} & 160& 82& 45  \\ \hline
{\ct GOLDENROD} & \textcolor{GOLDENROD} {$\blacksquare$} & 218& 165& 32& {\ct SILVER} &  \textcolor{SILVER} {$\blacksquare$} & 192& 192& 192  \\ \hline
{\ct GRAY} & \textcolor{GRAY} {$\blacksquare$} & 128& 128& 128& {\ct SKY BLUE} &  \textcolor{SKY BLUE} {$\blacksquare$} & 135& 206& 235  \\ \hline
{\ct GREEN} & \textcolor{GREEN} {$\blacksquare$} & 0& 255& 0& {\ct SLATEBLUE} &  \textcolor{SLATEBLUE} {$\blacksquare$} & 106& 90& 205  \\ \hline
{\ct GREEN YELLOW} & \textcolor{GREEN YELLOW} {$\blacksquare$} & 173& 255& 47& {\ct SLATE GRAY} &  \textcolor{SLATE GRAY} {$\blacksquare$} & 112& 128& 144  \\ \hline
{\ct HONEYDEW} & \textcolor{HONEYDEW} {$\blacksquare$} & 240& 255& 240& {\ct SPRING GREEN} &  \textcolor{SPRING GREEN} {$\blacksquare$} & 0& 255& 127  \\ \hline
{\ct HOT PINK} & \textcolor{HOT PINK} {$\blacksquare$} & 255& 105& 180& {\ct STEEL BLUE} &  \textcolor{STEEL BLUE} {$\blacksquare$} & 70& 130& 180  \\ \hline
{\ct INDIAN RED} & \textcolor{INDIAN RED} {$\blacksquare$} & 205& 92& 92& {\ct TAN} &  \textcolor{TAN} {$\blacksquare$} & 210& 180& 140  \\ \hline
{\ct INDIGO} & \textcolor{INDIGO} {$\blacksquare$} & 75& 0& 130& {\ct TEAL} &  \textcolor{TEAL} {$\blacksquare$} & 0& 128& 128  \\ \hline
{\ct IVORY} & \textcolor{IVORY} {$\blacksquare$} & 255& 255& 240& {\ct THISTLE} &  \textcolor{THISTLE} {$\blacksquare$} & 216& 191& 216  \\ \hline
{\ct IVORY BLACK} & \textcolor{IVORY BLACK} {$\blacksquare$} & 41& 36& 33& {\ct TOMATO } &  \textcolor{TOMATO } {$\blacksquare$} & 255& 99& 71  \\ \hline
{\ct KELLY GREEN} & \textcolor{KELLY GREEN} {$\blacksquare$} & 0& 128& 0& {\ct TURQUOISE} &  \textcolor{TURQUOISE} {$\blacksquare$} & 64& 224& 208  \\ \hline
{\ct KHAKI} & \textcolor{KHAKI} {$\blacksquare$} & 240& 230& 140& {\ct VIOLET} &  \textcolor{VIOLET} {$\blacksquare$} & 238& 130& 238  \\ \hline
{\ct LAVENDER} & \textcolor{LAVENDER} {$\blacksquare$} & 230& 230& 250& {\ct VIOLET RED} &  \textcolor{VIOLET RED} {$\blacksquare$} & 208& 32& 144  \\ \hline
{\ct LIME GREEN} & \textcolor{LIME GREEN} {$\blacksquare$} & 50& 205& 50& {\ct WHITE} &  \textcolor{WHITE} {$\blacksquare$} & 255& 255& 255  \\ \hline
{\ct MAGENTA} & \textcolor{MAGENTA} {$\blacksquare$} & 255& 0& 255& {\ct YELLOW} &  \textcolor{YELLOW} {$\blacksquare$} & 255& 255& 0  \\ \hline
\end{tabular}
\end{center}
\end{table}


\subsection{Texture Maps}
\label{info:texture_map}

There are various ways of prescribing the color of various objects within the computational domain, but there is also a way of pasting images onto the obstructions for the purpose of making the Smokeview images more realistic. This technique is known as ``texture mapping.'' For example, to apply a wood paneling image to a wall, add to the {\ct SURF} line defining the physical properties of the paneling the line:
\begin{lstlisting}
&SURF ID='wood paneling',..., TEXTURE_MAP='paneling.jpg', TEXTURE_WIDTH=1.,
      TEXTURE_HEIGHT=2. /
\end{lstlisting}
Assuming that a JPEG file called {\ct paneling.jpg} exists in the working directory, Smokeview should read it and display the image wherever the paneling is used. Note that the image does not appear when Smokeview is first invoked. It is an option controlled by the {\ct Show/Hide} menu. The parameters {\ct TEXTURE\_WIDTH} and {\ct TEXTURE\_HEIGHT} are the physical dimensions of the image. In this case, the JPEG image is of a 1~m wide by 2~m high piece of paneling. Smokeview replicates the image as often as necessary to make it appear that the paneling is applied where desired. Consider carefully how the image repeats itself when applied in a scene. If the image has no obvious pattern, there is no problem with the image being repeated. If the image has an obvious direction, the real triplet {\ct TEXTURE\_ORIGIN} should be added to the {\ct VENT} or {\ct OBST} line to which a texture map should be applied. For example,
\begin{lstlisting}
&OBST XB=1.,2.,3.,4.,5.,7., SURF_ID='wood paneling', TEXTURE_ORIGIN=1.,3.,5. /
\end{lstlisting}
applies paneling to an obstruction whose dimensions are 1~m by 1~m by 2~m, such that the image of the paneling is positioned at the point (1,3,5). The default value of {\ct TEXTURE\_ORIGIN} is (0,0,0), and the global default can be changed by added a {\ct TEXTURE\_ORIGIN} statement to the {\ct MISC} line.




\section{Repeated Objects: The \texorpdfstring{{\tt MULT}}{MULT} Namelist Group (Table \ref{tbl:MULT})}
\label{info:MULT}

Sometimes obstructions, holes and vents are repeated over and over in the input file. This can be tedious to create and make the input file hard to read. However, if a particular set of objects repeats itself in a regular pattern, you can use a utility known as a multiplier. If you want to repeat an obstruction, for example, create a line in the input file as follows:
 \begin{lstlisting}
&MULT ID='m1', DX=1.2, DY=2.4, I_LOWER=-2, I_UPPER=3, J_LOWER=0, J_UPPER=5 /
&OBST XB=x1,x2,y1,y2,z1,z2, MULT_ID='m1' /
\end{lstlisting}
This has the effect of making an array of obstructions according to the following formulae:
\begin{eqnarray*}  \hbox{\ct x1'} = \hbox{\ct x1} + \hbox{\ct DX0} + i \; \hbox{\ct DX}  &;& \hbox{\ct I\_LOWER} \le i \le \hbox{\ct I\_UPPER} \\
                   \hbox{\ct x2'} = \hbox{\ct x2} + \hbox{\ct DX0} + i \; \hbox{\ct DX}  &;& \hbox{\ct I\_LOWER} \le i \le \hbox{\ct I\_UPPER} \\
                   \hbox{\ct y1'} = \hbox{\ct y1} + \hbox{\ct DY0} + j \; \hbox{\ct DY}  &;& \hbox{\ct J\_LOWER} \le j \le \hbox{\ct J\_UPPER} \\
                   \hbox{\ct y2'} = \hbox{\ct y2} + \hbox{\ct DY0} + j \; \hbox{\ct DY}  &;& \hbox{\ct J\_LOWER} \le j \le \hbox{\ct J\_UPPER} \\
                   \hbox{\ct z1'} = \hbox{\ct z1} + \hbox{\ct DZ0} + k \; \hbox{\ct DZ}  &;& \hbox{\ct K\_LOWER} \le k \le \hbox{\ct K\_UPPER} \\
                   \hbox{\ct z2'} = \hbox{\ct z2} + \hbox{\ct DZ0} + k \; \hbox{\ct DZ}  &;& \hbox{\ct K\_LOWER} \le k \le \hbox{\ct K\_UPPER}
\end{eqnarray*}
In situations where the position of the obstruction needs shifting prior to the multiplication, use the parameters {\ct DX0}, {\ct DY0}, and {\ct DZ0}.

\begin{figure}[t]
\includegraphics[width=\textwidth,trim={0 2in 0 1in},clip]{SCRIPT_FIGURES/pyramid}
\caption[An example of the multiplier function]{An example of the multiplier function.}
\label{fig:mult}
\end{figure}

A variation of this idea is to replace the parameters, {\ct DX}, {\ct DY}, and {\ct DZ}, with a sextuplet called {\ct DXB}. The six entries in {\ct DXB} increment the respective values of the obstruction coordinates given by {\ct XB}. For example, the $x$ coordinates are transformed as follows:
\begin{eqnarray*}  \hbox{\ct x1'} = \hbox{\ct x1} + \hbox{\ct DX0} + n \; \hbox{\ct DXB(1)}  &;& \hbox{\ct N\_LOWER} \le n \le \hbox{\ct N\_UPPER} \\
                   \hbox{\ct x2'} = \hbox{\ct x2} + \hbox{\ct DX0} + n \; \hbox{\ct DXB(2)}  &;& \hbox{\ct N\_LOWER} \le n \le \hbox{\ct N\_UPPER}
\end{eqnarray*}
Notice that we use {\ct N\_LOWER} and {\ct N\_UPPER} to denote the range of {\ct N}. This more flexible input scheme allows you to create, for example, a slanted roof in which the individual roof segments shorten as they ascend to the top. This feature is demonstrated by the following short input file that creates a hollowed out pyramid using the four perimeter obstructions that form the outline of its base:
\begin{lstlisting}
&HEAD CHID='pyramid', TITLE='Simple demo of multiplier function' /
&MESH IJK=100,100,100, XB=0.0,1.0,0.0,1.0,0.0,1.0 /
&TIME T_END=0. /
&MULT ID='south', DXB=0.01,-.01,0.01,0.01,0.01,0.01, N_LOWER=0, N_UPPER=39 /
&MULT ID='north', DXB=0.01,-.01,-.01,-.01,0.01,0.01, N_LOWER=0, N_UPPER=39 /
&MULT ID='east',  DXB=-.01,-.01,0.01,-.01,0.01,0.01, N_LOWER=0, N_UPPER=39 /
&MULT ID='west',  DXB=0.01,0.01,0.01,-.01,0.01,0.01, N_LOWER=0, N_UPPER=39 /
&OBST XB=0.10,0.90,0.10,0.11,0.10,0.11, MULT_ID='south', COLOR='RED' /
&OBST XB=0.10,0.90,0.89,0.90,0.10,0.11, MULT_ID='north', COLOR='BLUE' /
&OBST XB=0.10,0.11,0.11,0.89,0.10,0.11, MULT_ID='west',  COLOR='GREEN' /
&OBST XB=0.89,0.90,0.11,0.89,0.10,0.11, MULT_ID='east',  COLOR='CYAN' /
&MULT ID='holes', DX=0.15, DZ=0.1, I_UPPER=1, K_UPPER=1 /
&HOLE XB=0.40,0.45,0.00,1.00,0.15,0.20, MULT_ID='holes' /
&TAIL /
\end{lstlisting}
The end result of this input file is to create a pyramid by repeating long, rectangular obstructions at the base of each face in a stair-step pattern. Note in this case the use of {\ct N\_LOWER} and {\ct N\_UPPER} which automatically cause FDS to repeat the obstructions in sequence rather than as an array.

Note that the {\ct MULT}iplication functionality works for {\ct MESH}, {\ct OBST}, {\ct HOLE}, {\ct VENT}, and {\ct INIT} lines. For a {\ct MESH}, it only applies to the bounds ({\ct XB}) of the mesh, not the number of cells.

Note also that if a {\ct COLOR} is specified on a line that includes a {\ct MULT\_ID}, this color will be applied to all replicates of the object. However, you can set {\ct COLOR='RAINBOW'} which will instruct FDS to randomly choose a color for each replicate object.

\subsection{Special Topic: Using {\ct MULT} for Mesh Refinement}
\label{info:multmeshrefine}

Note that objects and meshes in the {\ct MULT} array may be skipped using {\ct I\_LOWER\_SKIP} and {\ct I\_UPPER\_SKIP}, etc.  The $i$ from the equation above is skipped within this interval.  As an example of how this may be useful, consider the multi-mesh case below with refinement of the interior meshes.  The resulting mesh arrangement is shown in Fig.~\ref{fig:multmeshrefine}.

\begin{lstlisting}
&MULT ID='interior fine mesh array',
      DX=1.0,I_LOWER=1,I_UPPER=2,
      DZ=1.0,K_LOWER=1,K_UPPER=2 /

&MULT ID='exterior coarse mesh array',
      DX=1.0,I_LOWER=0,I_LOWER_SKIP=1,I_UPPER_SKIP=2,I_UPPER=3,
      DZ=1.0,K_LOWER=0,K_LOWER_SKIP=1,K_UPPER_SKIP=2,K_UPPER=3 /

&MESH IJK=8,1,8, XB=0.0,1.0,-0.5,0.5,0.0,1.0, MULT_ID='interior fine mesh array' /
&MESH IJK=4,1,4, XB=0.0,1.0,-0.5,0.5,0.0,1.0, MULT_ID='exterior coarse mesh array' /
\end{lstlisting}

\vskip2\baselineskip

\begin{figure}[h!]
\centering

\resizebox{0.5\textwidth}{!}{

\begin{picture}(345,320)(0,0)
\setlength{\unitlength}{0.015in}

\newsavebox{\mymesh}
\savebox{\mymesh}{
\begin{picture}(0,0)
\thinlines
\multiput( 0,20)(0,20){4}{\line(1,0){80}}
\multiput(20, 0)(20,0){4}{\line(0,1){80}}
\thicklines
\put(0,0){\framebox(80,80){ }}
\end{picture} }

\newsavebox{\mymeshrefine}
\savebox{\mymeshrefine}{
\begin{picture}(0,0)
\thinlines
\multiput( 0,10)(0,10){8}{\line(1,0){80}}
\multiput(10, 0)(10,0){8}{\line(0,1){80}}
\thicklines
\put(0,0){\framebox(80,80){ }}
\end{picture} }

% coarse exterior meshes
\put(  0,0){\usebox{\mymesh}}
\put( 80,0){\usebox{\mymesh}}
\put(160,0){\usebox{\mymesh}}
\put(240,0){\usebox{\mymesh}}

\put(  0,80){\usebox{\mymesh}}
\put(240,80){\usebox{\mymesh}}

\put(  0,160){\usebox{\mymesh}}
\put(240,160){\usebox{\mymesh}}

\put(  0,240){\usebox{\mymesh}}
\put( 80,240){\usebox{\mymesh}}
\put(160,240){\usebox{\mymesh}}
\put(240,240){\usebox{\mymesh}}

% refined interior meshes
\put( 80, 80){\usebox{\mymeshrefine}}
\put( 80,160){\usebox{\mymeshrefine}}
\put(160, 80){\usebox{\mymeshrefine}}
\put(160,160){\usebox{\mymeshrefine}}

\end{picture}

}

\caption[Using {\ct MULT} for mesh refinement]{Using {\ct MULT} for mesh refinement.}
\label{fig:multmeshrefine}

\end{figure}


\subsection{Special Topic: Using {\ct MULT} to make shapes out of obstructions}
\label{info:multobst}

Block obstructions made using an {\ct OBST} line are constrained to the box defined {\ct XB}.  However, if you create a block out of an array of obstructions---each of which can be as small as a single grid cell---then that block can be manipulated into one of four basic shapes: sphere, cylinder, cone or box.  The flow obstruction is created from the intersection of the {\ct OBST} array, created using a {\ct MULT\_ID}, and the {\ct SHAPE} defined on the {\ct OBST} line.  Note that this method may be memory intensive since each grid cell can be its own {\ct OBST}, similar to the way {\ct OBST} are decomposed when using {\ct BURN\_AWAY} for pyrolysis.

%With regard to the {\ct SURF\_ID},

The first step in carving out the shape is to create a {\ct MULT} line that defines the replication of the {\ct OBST}.  Then a {\ct SHAPE} is entered on the {\ct OBST} line together with whatever parameters are required; parameters are listed in Table~\ref{tab:obst_shape}.

\begin{table}[ht]
\caption[{\ct OBST SHAPE} parameters]{{\ct OBST SHAPE} parameters.}
\label{tab:obst_shape}
\centering
\begin{tabular}{|ll|}
\hline
{\ct SHAPE} \hfill   & Parameters (default values in Table~\ref{tbl:OBST})    \hfill    \\ \hline
{\ct 'SPHERE'}       & {\ct XYZ}, {\ct RADIUS}                                  \\
{\ct 'CYLINDER'}     & {\ct XYZ}, {\ct RADIUS}, {\ct HEIGHT}, {\ct ORIENTATION} \\
{\ct 'CONE'}         & {\ct XYZ}, {\ct RADIUS}, {\ct HEIGHT}, {\ct ORIENTATION} \\
{\ct 'BOX'}            & {\ct XYZ}, {\ct LENGTH}, {\ct WIDTH}, {\ct HEIGHT}, {\ct ORIENTATION}, {\ct THETA} \\ \hline
\end{tabular}
\end{table}

An example of a sphere is given below.  By default, the center of the sphere is at (0,0,0), so only the {\ct RADIUS} is required.  If the {\ct RADIUS} is larger than the half-width the {\ct OBST} array, this is not a problem, but the end result will not be a sphere.  If the {\ct RADIUS} is smaller than the half-width, this is also permissible, but it is inefficient.

\begin{lstlisting}
&MESH IJK=50,50,50, XB=-0.125,0.125,-0.125,0.125,-0.125,0.125/
&SURF ID='shape', COLOR='ORANGE'/
&MULT ID='cube array', DX=0.005,DY=0.005,DZ=0.005, I_UPPER=41,J_UPPER=41,K_UPPER=41/
&OBST XB=-0.105,-0.100,-0.105,-0.100,-0.105,-0.100
      MULT_ID='cube array'
      SURF_ID='shape'
      SHAPE='SPHERE'
      RADIUS=0.1/
\end{lstlisting}

\begin{figure}[ht]
\centering
\includegraphics[width=.7\textwidth,trim={0 0.5in 0 0.5in},clip]{SCRIPT_FIGURES/obst_sphere}
\caption[Creating an {\ct OBST} sphere using {\ct MULT} and {\ct SHAPE}]{Creating an {\ct OBST} sphere using {\ct MULT} and {\ct SHAPE}.}
\label{fig:obst_sphere}
\end{figure}

To create a cylinder we need a height and orientation in addition to the radius.  The position of the center of the bottom face of the cylinder {\ct XYZ} defaults to (0,0,0).  An example of a vertically oriented (default) cylinder is shown below in Fig.~\ref{fig:obst_cylinder}.  Note that the magnitude of the orientation vector is not important; the vector is only used to specify the direction.

A word of caution when using {\ct ORIENTATION} with the {\ct SHAPE} feature: Changing the orientation from the default (0,0,1) voids the area adjustment algorithm.  As a result, FDS cannot achieve the exact mass flux out of the surface as prescribed by the {\ct SURF} line and the precise area given by the geometry parameters for the {\ct SHAPE} on the {\ct OBST} line.  The mass flux FDS generates will be determined by {\ct SURF} line and the size of the grid cells the {\ct OBST} snaps to.  If reorientation is required, first run a sample case to see what total flow rate the surface is achieving (usually found in the {\ct CHID\_hrr.csv} file).  Then manually adjust your mass flux (or {\ct HRRPUA}) on the appropriate {\ct SURF} line.

\begin{lstlisting}
&SURF ID='shape', COLOR='DARK GRAY'/
&MULT ID='cube array', DX=0.005,DY=0.005,DZ=0.005, I_UPPER=41,J_UPPER=41,K_UPPER=41/
&OBST XB=-0.105,-0.100,-0.105,-0.100,-0.105,-0.100
      MULT_ID='cube array'
      SURF_ID='shape'
      SHAPE='CYLINDER'
      RADIUS=0.05
      HEIGHT=0.2
      XYZ=0,0,-0.1
      ORIENTATION=0,0,1/
\end{lstlisting}

\begin{figure}[ht]
\centering
\includegraphics[width=.7\textwidth,trim={0 .5in 0 .5in},clip]{SCRIPT_FIGURES/obst_cylinder}
\caption[Creating an {\ct OBST} cylinder using {\ct MULT} and {\ct SHAPE}]{Creating an {\ct OBST} cylinder using {\ct MULT} and {\ct SHAPE}.}
\label{fig:obst_cylinder}
\end{figure}

A cone needs basically the same input parameters as a cylinder.  The position of the center of the bottom face is specified using {\ct XYZ} and the {\ct RADIUS} of the bottom face, the {\ct HEIGHT}, and the {\ct ORIENTATION} must be specified.  An example is shown below in Fig~\ref{fig:obst_cone}.

\begin{lstlisting}
&SURF ID='shape', COLOR='FOREST GREEN'/
&MULT ID='cube array', DX=0.005,DY=0.005,DZ=0.005, I_UPPER=41,J_UPPER=41,K_UPPER=41/
&OBST XB=-0.105,-0.100,-0.105,-0.100,-0.105,-0.100
      MULT_ID='cube array'
      SURF_ID='shape'
      SHAPE='CONE'
      RADIUS=0.05
      HEIGHT=0.2
      XYZ=0,0,-0.1
      ORIENTATION=0,0,1/
\end{lstlisting}

\begin{figure}[ht]
\centering
\includegraphics[width=.7\textwidth,trim={0 .5in 0 .5in},clip]{SCRIPT_FIGURES/obst_cone}
\caption[Creating an {\ct OBST} cone using {\ct MULT} and {\ct SHAPE}]{Creating an {\ct OBST} cone using {\ct MULT} and {\ct SHAPE}.}
\label{fig:obst_cone}
\end{figure}

Finally, the box shape allows to define rotated cuboids. A box shape is defined locally by its {\ct HEIGHT}, {\ct WIDTH} and {\ct LENGTH}. The location of the box center is provided in {\ct XYZ}. The angle {\ct THETA} in degrees specifies a rotation of the box respect to the global $z$ axis, following right hand rule.
Subsequently, the {\ct ORIENTATION} direction vector allows for an orientation change respect to the {\ct THETA} rotated reference frame. This direction vector changes the box orientation such that the local {\ct HEIGHT} direction matches it.
A simple example is shown Fig~\ref{fig:obst_rotbox}.

\begin{lstlisting}
&SURF ID='shape', COLOR='GRAY'/
&MULT ID='cube array', DX=0.005,DY=0.005,DZ=0.005, I_UPPER=41,J_UPPER=41,K_UPPER=41/
&OBST XB=-0.105,-0.100,-0.105,-0.100,-0.105,-0.100
      MULT_ID='cube array'
      SURF_ID='shape'
      SHAPE='BOX'
      LENGTH=0.075
      WIDTH=0.025
      HEIGHT=0.05
      XYZ=0,0,0.01
      ORIENTATION=0.5,0,1
      THETA = 45. /
\end{lstlisting}

\begin{figure}[ht]
\centering
\includegraphics[width=.7\textwidth,trim={0 .5in 0 .5in},clip]{SCRIPT_FIGURES/obst_rotbox}
\caption[Creating an {\ct OBST} cone using {\ct MULT} and {\ct SHAPE}]{Creating an {\ct OBST} rotated box using {\ct MULT} and {\ct SHAPE}.}
\label{fig:obst_rotbox}
\end{figure}


\chapter{Fire and Thermal Boundary Conditions}

This chapter describes how to specify the thermal properties of solid objects. This is
the most challenging part of setting up the simulation. Why?  First,
for both real and simulated fires, the growth of the fire is very
sensitive to the thermal properties of the surrounding
materials. Second, even if all the material properties are known to
some degree, the physical phenomena of interest may not be simulated
properly due to limitations in the model algorithms or resolution of
the numerical mesh. It is your responsibility to supply the thermal
properties of the materials, and then assess the performance of the
model to ensure that the phenomena of interest are being captured.


\section{Basics}
\label{info:SURF_MATL_Basics}

By default, the outer boundary of the computational domain is assumed to be a solid boundary that is maintained at ambient temperature. The same is true for any obstructions that are added to the scene. To specify the properties of solids, use the namelist group {\ct SURF} (Section~\ref{info:SURF}). Solids are assumed to consist of layers that can be made of different materials.  The properties of each material required are designated via the {\ct MATL} namelist group (Section~\ref{info:MATL}).  These properties indicate how rapidly the materials heat up, and how they burn.  Each {\ct MATL} entry in the input file must have an {\ct ID}, or name, so that they may be associated with a particular {\ct SURF} via the parameter {\ct MATL\_ID}.  For example, the input file entries:
\begin{lstlisting}
&MATL ID='BRICK', CONDUCTIVITY=0.69, SPECIFIC_HEAT=0.84, DENSITY=1600. /
&SURF ID='BRICK WALL', MATL_ID='BRICK', COLOR='RED', BACKING='EXPOSED',
      THICKNESS=0.20 /
&OBST XB=0.1,5.0,1.0,1.2,0.0,1.0, SURF_ID='BRICK WALL' /
\end{lstlisting}
define a brick wall that is 4.9~m long, 1~m high, and 20~cm thick. Note that the thickness of the wall indicated by the {\ct OBST} line is independent of the {\ct THICKNESS} specified by the {\ct SURF} line.  The {\ct OBST} line defines the geometry of the obstruction (i.e., how the obstruction is seen by the flow solver).  The {\ct SURF} line defines the heat transfer characteristics of the obstruction (i.e., how the obstruction is seen by the 1D solid phase solver).  This allows an obstruction to snap to the local grid but still have the heat transfer solution reflect the actual thickness.



\section{Surface Temperature and Heat Flux}

This section describes how to specify simple thermal boundary conditions. These are often used when there is little or no
information about the properties of the solid materials. If the properties of the materials are known, it is better to specify these
properties and let the model compute the heat flux to, and temperature of, the walls and other solid surfaces.


\subsection{Specified Solid Surface Temperature}
\label{info:specified_temperature}

Usually, the thermal properties of a solid boundary are specified via the
{\ct MATL} namelist group, which is in turn invoked by the {\ct SURF} entry via
the character string {\ct MATL\_ID}. However, sometimes it is convenient to
specify a fixed temperature boundary condition, in which case set
{\ct TMP\_FRONT} to be the surface temperature in units of $^\circ$C:

\begin{lstlisting}
&SURF ID='HOT WALL', COLOR='RED', TMP_FRONT=200. /
\end{lstlisting}

\noindent
Note that there is no need to specify a {\ct MATL\_ID} or {\ct THICKNESS}. Because the wall is to be maintained at the given temperature,
there is no need to say anything about its material composition or thickness.



\subsection{Special Topic: Convective Heat Transfer Options}
\label{info:convection}

This section is labeled as a special topic because normally you do not need to modify the convective heat transfer model in FDS. However, there are special cases for which the default model may not be adequate, and this section describes some options.

\subsubsection{Default Convective Heat Transfer Model}

In an LES calculation, the convective heat transfer coefficient, $h$, is based on a combination of natural and forced convection correlations:
\be \dq_{\rm c}'' = h \, (T_{\rm g} - T_{\rm w}) \quad \hbox{W/m}^2 \quad ; \quad
    h = \max \, \left[ \; C\, |T_{\rm g}-T_{\rm w}|^\ot \; ,
      \;  \frac{k}{L} \, \NU \; ,
      \; \frac{k}{\dn/2}\right]  \quad  \si{W/(m^2.K)}
\ee
where $C$ is a empirical coefficient for natural convection (1.52 for a horizontal plate and 1.31 for a vertical plane or cylinder)~\cite{Holman:1}, $L$ is a characteristic length related to the size of the physical obstruction, $k$ is the thermal conductivity of the gas, and $\dn$ is the gas phase cell size. The Nusselt number (Nu) depends on the geometric and flow characteristics. For many flow regimes, it has the form:
\be
   \NU = C_1 + C_2 \, \RE^n \, \PR^m  \quad ; \quad \RE = \frac{\rho |\bu| L}{\mu} \quad ; \quad \PR = 0.7
\ee
For planar surfaces, the default values are $C_1=0$, $C_2=0.037$, $n=0.8$, $m=0.33$, and $L=1$~m. For cylindrical surfaces, the default values are $C_1=0$, $C_2=0.683$, $n=0.466$, $m=0.33$, and $L=D$, the diameter of the cylinder. For spherical surfaces, the default values are $C_1=2$, $C_2=0.6$, $n=0.5$, $m=0.33$, and $L=D$, the diameter of the sphere. Note that for a sphere, the coefficient for natural convection, $C$, is assumed to be zero. It is possible to change these values for a particular application, but it is not possible to find a set of parameters that is appropriate for the wide variety of scenarios considered. Various correlations for planes, cylinders, and spheres can be found in Refs.~\cite{Holman:1,Incropera:1}.

The last term of the $h$ formula aims to ensure that the LES convective heat flux converges to the DNS heat flux at fine resolutions.

You can change the values of the empirical coefficient for natural convection, $C$, by specifying \linebreak[4]{\ct C\_HORIZONTAL} and {\ct C\_VERTICAL} on the {\ct SURF} line. The length scale, $L$, is specified by \linebreak[4]{\ct CONVECTION\_LENGTH\_SCALE} on the {\ct SURF} line. You can change the empirical coefficients for the forced convection model by using {\ct C\_FORCED\_CONSTANT}, {\ct C\_FORCED\_RE}, {\ct C\_FORCED\_RE\_EXP}, and \linebreak[4]{\ct C\_FORCED\_PR\_EXP} for the constants $C_1$, $C_2$, $n$, and $m$ in the Nusselt number correlation, all of which are input on the {\ct SURF} line. Note that setting both $C_1$ and $C_2$ zero turns on their default values.

\subsubsection{Specified Convective Heat Transfer Coefficient}

If you want to specify the convective heat transfer coefficient, you can set it to a constant using \\
{\ct HEAT\_TRANSFER\_COEFFICIENT} on the {\ct SURF} line in units of \si{W/(m$^2$.K)}. If the back side of the solid obstruction faces the exterior of the computational domain and the solid conducts heat, you can specify the heat transfer coefficient of the back side using {\ct HEAT\_TRANSFER\_COEFFICIENT\_BACK}. This back side condition is appropriate for a {\ct SURF} line with {\ct BACKING='VOID'} or {\ct BACKING='EXPOSED'}.

\subsubsection{Specifying the Heat Flux at a Solid Surface}

Instead of altering the convective heat transfer coefficient, you may specify a fixed heat flux directly.  Two methods are available to do this.  The first is to specify a {\ct NET\_HEAT\_FLUX} in units of kW/m$^2$.  When this is specified FDS will compute the surface temperature required to ensure that the combined radiative and convective heat flux from the surface is equal to the {\ct NET\_HEAT\_FLUX}.  The second method is to specify separately the {\ct CONVECTIVE\_HEAT\_FLUX}, in units of kW/m$^2$, and the radiative heat flux.  The radiative heat flux is specified  by setting both {\ct TMP\_FRONT} and {\ct EMISSIVITY} appropriately on the {\ct SURF} line. Note that if you wish there to be only a convective heat flux from a surface, then the {\ct EMISSIVITY} should be set to zero.  If {\ct NET\_HEAT\_FLUX} or {\ct CONVECTIVE\_HEAT\_FLUX} is positive, the wall heats up the surrounding gases. If {\ct NET\_HEAT\_FLUX} or {\ct CONVECTIVE\_HEAT\_FLUX} is negative, the wall cools the surrounding gases.

\subsubsection{Logarithmic Law of the Wall}

Near-wall treatments, such as wall models or wall functions, aim to mimic the sudden change from molecular to turbulent transport close to the walls using algebraic formulations without the need of resolving the otherwise computationally expensive region of the near-wall flow-field. The main theory follows dimensional analysis based on the idea that shear at the wall is constant. Accordingly, the non-dimensional velocity $u^+$ is calculated using a wall function \cite{FDS_Tech_Guide}.

By analogy, we define the non-dimensional temperature $T^+ \equiv (T_{\rm g}-T_{\rm w})/T_\tau$, where $T_{\rm g}$ is the gas temperature of the first off-wall grid cell and $T_\tau$ is defined with the wall heat flux, $\dot{q}''_{\rm w}$, as $T_\tau = \dot{q}''_{\rm w}/\rho_{\rm w} u_\tau c_{\rm p}$. The local heat transfer coefficient is then obtained from
\begin{equation}
h = \frac{\dot{q}''_{\rm w}}{T_{\rm g}-T_{\rm w}} = \frac{\rho_{\rm w} \, c_{\rm p} \, u_\tau}{T^+}
\end{equation}
Refer to the FDS Tech Guide \cite{FDS_Tech_Guide} for further details of the formulation. To specify this heat transfer model for a particular surface, set {\ct HEAT\_TRANSFER\_MODEL} equal to {\ct 'LOGLAW'} on the {\ct SURF} line.

\subsubsection{Free Convection, Horizontal Cylinder}

For some verification and validation cases, it is useful to employ a special correlation for free convection from a horizontal cylinder~\cite{Incropera:1}:
\be
   h = \hbox{Nu} \, \frac{k}{D}  \quad ; \quad \hbox{Nu} = \left( 0.60 + \frac{ 0.387 \, \hbox{Ra}^{1/6} }{\left[ 1+ (0.559/\hbox{Pr})^{9/16} \right]^{8/27}} \right)^2  \quad ; \quad \hbox{Ra} = \frac{2 \, g \, (T_{\rm s}-T_\infty)D^3}{ (T_{\rm s}+T_\infty) \nu \alpha}
\ee
where $\hbox{Nu}$ is the Nusselt number, $k$ is the thermal conductivity of the gas, $D$ is the diameter of the cylinder, Ra is the Rayleigh number, Pr is the Prandtl number, $T_{\rm s}$ is the surface temperature, $T_\infty$ is the ambient or surrounding gas temperature, $g$ is the acceleration of gravity, $\nu=\mu/\rho$ is the kinematic viscosity of the gas, and $\alpha=k/(\rho c_p)$ is the thermal diffusivity. To specify this heat transfer model for a particular surface, set {\ct HEAT\_TRANSFER\_MODEL} equal to {\ct 'FREE HORIZONTAL CYLINDER'} on the {\ct SURF} line.


\subsection{Special Topic: Adiabatic Surfaces}
\label{info:adiabatic}

For some special applications, it is often desired that a solid surface be adiabatic, that is, there is no net heat transfer (radiative and convective) from the gas to the solid. For this case, all that must be prescribed on the {\ct SURF} line is {\ct ADIABATIC=.TRUE.}, and nothing else.  FDS will compute a wall temperature so that the sum of the net convective and radiative heat flux is zero.  Specifying a surface as {\ct ADIABATIC} will result in FDS defining {\ct NET\_HEAT\_FLUX=0} and {\ct EMISSIVITY=1}.

No solid surface is truly adiabatic; thus, the specification of an adiabatic boundary condition should be used for diagnostic purposes only.




\section{Heat Conduction in Solids}
\label{info:MATL}

Specified temperature or heat flux boundary conditions are easy to apply, but only of limited usefulness in real fire scenarios. In most cases, walls, ceilings and floors are made up of several layers of lining materials. The {\ct MATL} namelist group is used to define the properties of the materials that make up boundary solid surfaces. A solid boundary can consist of multiple layers\footnote{The maximum number of material layers is 20. The maximum number of material components is 20.} of different materials, and each layer can consist of multiple material components.

\subsection{Structure of Solid Boundaries}

Material layers and components are specified on the {\ct SURF} line via the array called {\ct MATL\_ID(IL,IC)}. The argument {\ct IL} is an integer indicating the layer index, starting at 1, the layer at the exterior boundary. The argument {\ct IC} is an integer indicating the component index. For example, {\ct MATL\_ID(2,3)='BRICK'} indicates that the third material component of the second layer is {\ct BRICK}. In practice, the materials are often listed as in the following example:
\begin{lstlisting}
&MATL ID             = 'INSULATOR'
      CONDUCTIVITY   = 0.041
      SPECIFIC_HEAT  = 2.09
      DENSITY        = 229. /

&SURF ID        = 'BRICK WALL'
      MATL_ID   = 'BRICK','INSULATOR'
      COLOR     = 'RED'
      BACKING   = 'EXPOSED'
      THICKNESS = 0.20,0.10 /
\end{lstlisting}
Without arguments, the parameter {\ct MATL\_ID} is assumed to be a list of the materials in multiple layers, with each layer consisting of only a single material component.

When a set of {\ct SURF} parameters is applied to the face of an {\ct OBST}, the first {\ct MATL\_ID} defines the first layer of solid material. The other {\ct MATL\_ID}s are applied in succession. If {\ct BACKING='EXPOSED'}, the last {\ct MATL\_ID} is applied to the opposite face of the {\ct OBST}, assuming that the {\ct OBST} is zero or one grid cells thick. If the {\ct OBST} is thicker than one grid cell, then {\ct BACKING='EXPOSED'} is not defined, and it will be treated as if the condition {\ct BACKING='VOID'} was set. If in the example above, {\ct BRICK WALL} was applied to the entire {\ct OBST} using {\ct SURF\_ID}, then when doing a heat transfer calculation from the $+x$ face to the $-x$ face, FDS would consider the {\ct OBST} to be {\ct BRICK} followed by {\ct INSULATOR} and the same for a heat transfer
calculation from the $-x$ face to the $+x$ face.  To avoid this, specify a second {\ct SURF} that has the reverse {\ct MATL\_ID} and use {\ct SURF\_ID6} to apply the two {\ct SURF} definitions to opposite faces of the {\ct OBST}.

Mixtures of solid materials within the same layer can be defined using the {\ct MATL\_MASS\_FRACTION} keyword. This parameter has the same two indices as the {\ct MATL\_ID} keyword. For example, if the brick layer contains some additional water, the input could look like this:
\begin{lstlisting}
&MATL ID            = 'WATER'
      CONDUCTIVITY  = 0.60
      SPECIFIC_HEAT = 4.19
      DENSITY       = 1000. /

&SURF ID                        = 'BRICK WALL'
      MATL_ID(1,1:2)            = 'BRICK','WATER'
      MATL_MASS_FRACTION(1,1:2) = 0.95,0.05
      MATL_ID(2,1)              = 'INSULATOR'
      COLOR                     = 'RED'
      BACKING                   = 'EXPOSED'
      THICKNESS                 = 0.20,0.10 /  <--- for layers 1 and 2
\end{lstlisting}
In this example, the first layer of material, Layer~1, is composed of a mixture of brick and water. This is given by the {\ct MATL\_ID} array which specifies Component~1 of Layer~1 to be brick, and Component~2 of Layer~1 to be water. The mass fraction of each is specified via {\ct MATL\_MASS\_FRACTION}. In this case, brick is 95~\%, by mass, of Layer 1, and water is 5~\%.

It is important to notice that the components of the solid mixtures are treated as pure substances with no voids. The density of the mixture is
\be
\rho = \left(\sum_i\frac{Y_i}{\rho_i}\right)^{-1}
\ee
where $Y_i$ are the material mass fractions and $\rho_i$ are the material bulk densities defined on the {\ct MATL} lines. In the example above, the resulting density of the wall would be about 1553~kg/m$^3$. The fact that the wall density is smaller than the density of pure brick may be confusing, but can be explained easily. If the wall can contain water, the whole volume of the wall can not be pure brick. Instead there are voids (pores) that are filled with water. If the water is taken away, there is only about 1476~kg/m$^3$ of brick left. To have a density of 1600~kg/m$^3$ for a partially void wall, a higher density should be used for the pure brick.

\subsection{Thermal Properties}

\label{info:thermal_properties}

For any solid material, specify its thermal {\ct CONDUCTIVITY} (\si{W/(m.K)}), {\ct DENSITY} (kg/m$^3$), {\ct SPECIFIC\_HEAT} (\si{kJ/(kg.K)}), and {\ct EMISSIVITY}\footnote{The {\ct EMISSIVITY} of a {\ct MATL} component of a {\ct SURF} takes precedence over the {\ct EMISSIVITY} specified on the {\ct SURF} line. This is true even if no {\ct EMISSIVITY} is explicitly specified on the {\ct MATL} line. Its default value still takes precedence over whatever might be specified on the {\ct SURF} line.} (0.9 by default). Both {\ct CONDUCTIVITY} and {\ct SPECIFIC\_HEAT} can be functions of temperature. {\ct DENSITY} and {\ct EMISSIVITY} cannot. Temperature-dependence is specified using the {\ct RAMP} convention. As an example, consider Marinite, a wall material suitable for high temperature applications:
\begin{lstlisting}
&MATL ID                 = 'MARINITE'
      EMISSIVITY         = 0.8
      DENSITY            = 737.
      SPECIFIC_HEAT_RAMP = 'c_ramp'
      CONDUCTIVITY_RAMP  = 'k_ramp' /
&RAMP ID='k_ramp', T= 24., F=0.13 /
&RAMP ID='k_ramp', T=149., F=0.12 /
&RAMP ID='k_ramp', T=538., F=0.12 /
&RAMP ID='c_ramp', T= 93., F=1.172 /
&RAMP ID='c_ramp', T=205., F=1.255 /
&RAMP ID='c_ramp', T=316., F=1.339 /
&RAMP ID='c_ramp', T=425., F=1.423 /
\end{lstlisting}
Notice that with temperature-dependent quantities, the {\ct RAMP} parameter {\ct T} means Temperature, and {\ct F} is the value of either the specific heat or conductivity. In this case, neither {\ct CONDUCTIVITY} nor {\ct SPECIFIC\_HEAT} is given on the {\ct MATL} line, but rather the {\ct RAMP} names.

The solid material can be given an {\ct ABSORPTION\_COEFFICIENT} (1/m) that allows the radiation to penetrate and absorb into the solid. Correspondingly, the emission of the material is based on the internal temperatures, not just the surface. Note that you can only apply materials with an {\ct ABSORPTION\_COEFFICIENT} to planar surfaces, not cylinders or spheres.




\subsection{Back Side Boundary Conditions}
\label{info:BACKING}

The layers of a solid boundary are listed in order from the surface. By default, if the obstruction is less than or equal to one cell thick, then the innermost layer will be exposed to the air temperature on the back side.  If the obstruction is on the boundary of the domain or is more than one cell thick, then it is assumed to back up to an air gap at ambient temperature. For example, a thin steel plate (i.e. thickness less than or equal to the grid) would use the FDS predicted temperatures on either side of the plate for predicting heat transfer.

There are other back side boundary conditions that can be applied. One is to assume that the wall backs up to an insulated material in which case no heat is lost to the backing material. The expression {\ct BACKING='INSULATED'} on the {\ct SURF} line prevents any heat loss from the back side of the material. Use of this condition means that you  do not have to specify properties of the inner insulating material because it is assumed to be perfectly insulated.

If the wall is assumed to back up to the room on the other side of the wall and you want FDS to calculate the heat transfer through the wall into the space behind the wall, the attribute {\ct BACKING='EXPOSED'} should be listed on the {\ct SURF} line. This feature only works if the wall {\ct OBST} is less than or equal to one mesh cell thick, and if there is a non-zero volume of computational domain on the other side of the wall {\ct OBST}. Obviously, if the wall is an external boundary of the domain, the heat is lost to an ambient temperature void. The same happens if the back side gas cell cannot be found (i.e. the wall {\ct OBST} is greater than one cell thick).  This is the default boundary conditions.

If the wall is assumed to always back up to the ambient, then the attribute {\ct BACKING='VOID'} should be set.

The back side emissivity of the surface can be controlled by specifying {\ct EMISSIVITY\_BACK} on the {\ct SURF} line. If not specified, the back side emissivity will be calculated during the simulations as a mass-weighted sum of the {\ct MATL} emissivities.

\subsection{Initial and Back Side Temperature}
\label{info:TMP_INNER}

By default, the initial temperature of the solid material is set to ambient ({\ct TMPA} on the {\ct MISC} line). Use {\ct TMP\_INNER} on the {\ct SURF} line to specify a different initial temperature of the solid. The layers of the surface can have different initial temperatures. Also, the back side temperature boundary condition of a solid can be set using the parameter {\ct TMP\_BACK} on the {\ct SURF} line. {\ct TMP\_BACK} is not the actual back side surface temperature, but rather the gas temperature to which the back side surface is exposed. This parameter has no meaning for surfaces with {\ct BACKING='EXPOSED'} or {\ct BACKING='INSULATED'}.

As an alternative to {\ct TMP\_INNER} one can also use {\ct RAMP\_T\_I} to specify the name of a {\ct RAMP} containing a depth vs. temperature profile for the surface.

Note that the parameters {\ct TMP\_INNER} and {\ct TMP\_BACK} are only meaningful for solids with specified {\ct THICKNESS} and material properties (via the {\ct MATL\_ID} keyword).




\subsection{Walls with Different Materials Front and Back}
\label{info:EXPOSED}

If you have an {\ct OBST} that is one cell thick with gas cells on both sides (i.e., the obstruction is not at the edge of the domain) and you apply the attribute {\ct BACKING='EXPOSED'}, then FDS calculates the heat conduction through the entire {\ct THICKNESS}, and it uses the gas phase temperature and heat flux on the front and back sides for boundary conditions. A redundant calculation is performed on the opposite side of the obstruction.  FDS always applies a {\ct SURF} to an obstruction by having the first layer be the exposed surface of the face and the last layer as the opposite face.  Take for example the {\ct SURF} definition below and assume that the grid spacing is 10 cm.  On the -x side of the {\ct OBST}, layer 1 will be {\ct MATERIAL A}, layer 2 will be {\ct MATERIAL B}, and layer 3 will be the last {\ct MATERIAL A}.  On the +x side the {\ct SURF} will be applied in the same manner.

\begin{lstlisting}
&OBST XB=0.1,0.2,...., SURF_ID='SYMMETRIC'/
&SURF ID                 = 'SYMMETRIC'
      COLOR              = 'ANTIQUE WHITE'
      BACKING            = 'EXPOSED'
      MATL_ID(1:3,1)     = 'MATERIAL A','MATERIAL B','MATERIAL A'
      THICKNESS(1:3)     = 0.1,0.2,0.1 /
\end{lstlisting}

For example, take the {\ct SURF} definition below and assume that the grid spacing is 10 cm.  On the -x side of the {\ct OBST}, layer 1 will be {\ct MATERIAL A}, layer 2 will be {\ct MATERIAL B}, and layer 3 will be {\ct MATERIAL C}.  On the +x side, the {\ct SURF} will be applied in the same manner, layer 1 will be {\ct MATERIAL A}, layer 2 will be {\ct MATERIAL B}, and layer 3 will be {\ct MATERIAL C}.  This means that both sides of the {\ct OBST} will compute heat transfer assuming {\ct MATERIAL A} is the first layer.

\begin{lstlisting}
&OBST XB=0.1,0.2,...., SURF_ID='NON-SYMMETRIC'/
&SURF ID                 = 'NON-SYMMETRIC'
      COLOR              = 'ANTIQUE WHITE'
      BACKING            = 'EXPOSED'
      MATL_ID(1:3,1)     = 'MATERIAL A','MATERIAL B','MATERIAL C'
      THICKNESS(1:3)     = 0.1,0.2,0.1 /
\end{lstlisting}

Therefore, if you apply the attribute {\ct BACKING='EXPOSED'} on a {\ct SURF} line that is applied to a zero or one-cell thick
obstruction, you should be careful of how you specify multiple layers. If the layering is symmetric, the same {\ct SURF} line can
be applied to both sides. However, if the layering is not symmetric, you must create two separate {\ct SURF} lines and apply
one to each side. For example, a hollow box column that is made of steel and covered on the outside by a layer of insulation
material and a layer of plastic on top of the insulation material, would have to be described with two {\ct SURF} lines like the following:
\begin{lstlisting}
&SURF ID                 = 'COLUMN EXTERIOR'
      COLOR              = 'ANTIQUE WHITE'
      BACKING            = 'EXPOSED'
      MATL_ID(1:3,1)     = 'PLASTIC','INSULATION','STEEL'
      THICKNESS(1:3)     = 0.002,0.036,0.0063 /

&SURF ID                 = 'COLUMN INTERIOR'
      COLOR              = 'BLACK'
      BACKING            = 'EXPOSED'
      MATL_ID(1:3,1)     = 'STEEL','INSULATION','PLASTIC'
      THICKNESS(1:3)     = 0.0063,0.036,0.002 /
\end{lstlisting}
If, in addition, the insulation material and plastic are combustible, and their burning properties are specified on the appropriate {\ct MATL} lines,
then you need to indicate which side of the column would generate the fuel vapor. In this case, the steel is impermeable; thus you should add the parameter
{\ct LAYER\_DIVIDE=2.0} to the {\ct SURF} line labeled {\ct 'COLUMN EXTERIOR'} to indicate that fuel vapors formed by the heating of the
two first layers ({\ct 'PLASTIC'} and {\ct 'INSULATION'}) are to be driven out of that surface.
You need to also specify {\ct LAYER\_DIVIDE=0.0} on the {\ct SURF} line labeled {\ct 'COLUMN INTERIOR'} to indicate that no fuel
vapors are to driven into the interior of the column. In fact, values from 0.0 to 1.0 would work equally because the material
{\ct 'STEEL'} would not generate any fuel vapors.

By default, {\ct LAYER\_DIVIDE} is 0.5 times the number of layers for surfaces with {\ct EXPOSED} backing, and equal to the number of
layers for other surfaces.

\subsection{Special Topic: Specified Internal Heat Source}

\label{info:INTERNAL_HEAT_SOURCE}

The condensed phase heat conduction equation has a source term that describes the internal sources and sinks of energy.
There are three types of sources that contribute to this term:
heats of reaction for the pyrolysis (see Section~\ref{info:solid_pyrolysis}),
internal absorption and emission of radiation (see Section~\ref{info:liquid_fuels}), and the source specified by the user.
An example of the case where specified heat source could be needed is the heating of electrical cables due to internal current.

You can specify the internal source term for each layer of the surface using {\ct INTERNAL\_HEAT\_SOURCE} on the {\ct SURF} line.
Its units are {\si kW/m$^3$} and the default value is zero.
In the example below, the cylindrical surface describing a cable consists of an outer plastic layer and inner core of metal.
The metal core is heated with a power of 300 {\si kW/m$^3$}.
\begin{lstlisting}
&SURF ID                     = 'Cable'
      THICKNESS              = 0.002,0.008
      MATL_ID(1,1)           = 'PLASTIC'
      MATL_ID(2,1)           = 'METAL'
      GEOMETRY               = 'CYLINDRICAL'
      LENGTH                 = 0.1
      INTERNAL_HEAT_SOURCE   = 0.,300. /
\end{lstlisting}

\subsection{Special Topic: Non-Planar Walls and Targets}

\label{info:GEOMETRY}

All obstructions in FDS are assumed to conform to the rectilinear
mesh, and all bounding surfaces are assumed to be flat
planes. However, many objects, like cables, pipes, and ducts, are not
flat. Even though these objects have to be represented in FDS as
``boxes,'' you can still perform the internal heat transfer
calculation as if the object were really cylindrical or spherical. For
example, the input lines:
\begin{lstlisting}
&OBST XB=0.0,5.0,1.1,1.2,3.4,3.5, SURF_ID='CABLE' /
&SURF ID='CABLE', MATL_ID='PVC', GEOMETRY='CYLINDRICAL', THICKNESS=0.01 /
\end{lstlisting}
can be used to model a power cable that is 5~m long, cylindrical in
cross section, 2~cm in diameter. The heat transfer calculation is
still one-dimensional; that is, it is assumed that there is a uniform
heat flux all about the object. This can be somewhat confusing because
the cable is represented as an obstruction of square cross section,
with a separate heat transfer calculation performed at each face, and
no communication among the four faces. Obviously, this is not an ideal
way to do solid phase heat transfer, but it does provide a reasonable
bounding surface temperature for the gas phase calculation. More
detailed assessment of a cable would require a two or
three-dimensional heat conduction calculation, which is not included
in FDS. Use {\ct GEOMETRY='SPHERICAL'} to describe a spherical object.


\subsection{Special Topic: Solid Phase Numerical Gridding Issues}
\label{info:solid_phase_stability}

To compute the temperature and reactions inside the solids, FDS solves
the one-dimensional heat transfer equation numerically. The size of
the mesh cells on the surface of the solid is automatically chosen
using a rule that makes the cell size smaller than the square root of
the material diffusivity $(k/\rho c)$. By default, the solid mesh
cells increase towards the middle of the material layer and are smallest
on the layer boundaries.

The default parameters are usually appropriate for simple heat transfer calculations but sometimes the use of pyrolysis reactions
makes the temperatures and burning rate fluctuate. Adjustments may also be needed in case of
extremely transient heat transfer situations. The numerical accuracy and stability of the solid phase solution may be improved by
one of the following methods:
\begin{description}
\item[Make the mesh density more uniform ] inside the material by setting {\ct STRETCH\_FACTOR(NL)=1.} on the {\ct SURF} line. This will generate a perfectly uniform mesh for layer number {\ct NL}. (This happens automatically if the layer contains one or more reacting materials.) Values between 1 and 2 give different levels of stretching. Note that {\ct STRETCH\_FACTOR} needs to be specified for all the layers.
\item[Make the mesh cells smaller] by setting {\ct CELL\_SIZE\_FACTOR} less than 1.0. For example, a value of 0.5 makes the mesh cells half the size. The scaling always applies to all layers.
\item[Improve the time resolution] by setting {\ct WALL\_INCREMENT=1} on the {\ct TIME} line. This forces the solid phase temperatures to be solved on every time step.
\item[Limit the number of cells in a layer] by setting {\ct N\_LAYER\_CELLS\_MAX}. This array input has a default of 1000.
\end{description}
If all the material components of the surface are reacting, and the pyrolysis reactions have no solid residue, the thickness of
the surface is going to shrink when the surface reacts. Each of the shrinking layers will vanish from the computation when its thickness gets
smaller than a prescribed limiting value. This value can be set on a {\ct SURF} line via {\ct MINIMUM\_LAYER\_THICKNESS} keyword,
defaulting to $1 \times 10^{-6}$~m. When all the material of a shrinking surface is consumed but {\ct BURN\_AWAY} is not
prescribed, the surface temperature is set to {\ct TMP\_BACK}, convective heat flux to zero and burning rate to zero.

See Section~\ref{solid_phase_verification} for ways to check and improve the accuracy of the solid phase calculation.


\subsection{Solid Heat Transfer 3D (Beta)}
\label{info:ht3d}

The conduction model described in the previous sections does not account for lateral heat transfer within a solid.  Further, if a solid is immersed within a gas phase region it must be only one cell thick in order to communicate with neighboring gas phase regions for surface boundary conditions.  These issues are addressed by the solid heat transfer 3D ({\ct HT3D}) method, currently in beta testing in FDS.

\subsubsection*{Invoking the 3D Heat Transfer Model (HT3D)}

The method is invoked by adding {\ct {HT3D=.TRUE.}} to an {\ct {OBST}} line.  The material properties for the solid are obtained either from a {\ct {MATL\_ID}} on the {\ct {OBST}} line (simple heat transfer) or from a {\ct SURF\_ID} (typically used in conjunction with pyrolysis).

The thermal properties of the material are uniform within a cell.  You may connect multiple {\ct {OBST}} regions.  If you want layers of material, you must use a different {\ct {OBST}} for each layer, and each layer must be at least one cell thick.  Note the difference here between the 1D and 3D models---at present, each layer of a material must be explicitly resolved by the 3D model using the Eulerian grid.  That is, at present, lateral heat transfer is not possible with ``thin obstructions'' with zero thickness.

The thermal boundary conditions for the solid are taken from a {\ct SURF} associated with the faces of the {\ct OBST}.  The usual rules for associating {\ct SURF\_ID} with an {\ct OBST} apply: if only one {\ct SURF\_ID} is given, it applies to all six faces of the {\ct OBST}, if different thermal conditions apply to different faces {\ct SURF\_IDS} or {\ct SURF\_ID6} must be used.

\subsubsection*{Simple Heat Transfer}
\label{sec:ht_only}

The default {\ct SURF} for an {\ct OBST} is {\ct 'INERT'}, which is a Dirichlet condition for the surface temperature set to ambient.  If two-way coupling with the gas phase is desired, then the {\ct {SURF}} associated with the {\ct {OBST}} face should have {\ct {HT3D=.TRUE.}} and, generally, no other specified thermal boundary condition.  For example,
\begin{lstlisting}
&MATL ID='steel', .../
&SURF ID='s1', HT3D=.TRUE./
&OBST XB=..., HT3D=.TRUE., MATL_ID='steel', SURF_ID='s1'/
\end{lstlisting}
The exception to this rule is that an {\ct EXTERNAL\_FLUX} may be applied together with {\ct {HT3D=.TRUE.}} on {\ct SURF}.  The user should make sure that the {\ct {SURF}} does not also have an associated {\ct {MATL\_ID}}, which implements the 1D heat conduction model.

\subsubsection*{Internal Heat Sources}
\label{sec:heat_sources}

Volumetric heat sources may be applied inside the solid.  Below is an example using an {\ct INIT} line, where {\ct HRRPUV} is in units of \si{kW/m^3}:
\begin{lstlisting}
&INIT XB=-.1,.1,-.1,.1,-.1,.1, HRRPUV=1/
\end{lstlisting}

You can also use {\ct INTERNAL\_HEAT\_SOURCE} in \si{kW/m^3} on the {\ct OBST} line as shown in the example below.  In this case, the heat source is applied to each cell of the {\ct OBST}.
\begin{lstlisting}
&MATL ID='orange', .../
&SURF ID='SPHERE', HT3D=.TRUE./
&OBST XB=..., HT3D=.TRUE., MATL_ID='orange', SURF_ID='SPHERE', INTERNAL_HEAT_SOURCE=200./
\end{lstlisting}

\subsubsection*{Internal Radiation}
\label{sec:radiation_parameters}

The parameters affecting in-depth radiation absorption are the material's refractive index and absorption coefficient.  They are specified on the MATL line:
\begin{lstlisting}
&MATL ID='...', REFRACTIVE_INDEX=1.33, ABSORPTION_COEFFICIENT=1000, .../
\end{lstlisting}



\section{Simple Pyrolysis Models}

FDS has several approaches for describing the pyrolysis of solids and liquids. The approach to take depends largely
on the availability of material properties and the appropriateness of the underlying pyrolysis model.
Note that all pyrolysis models in FDS require that you explicitly define the gas phase reaction. See Chapter~\ref{chap:combustion} for details.
It should also be noted that the user has to use only one pyrolysis model at a time.

\subsection{A Gas Burner with a Specified Heat Release Rate}

\label{info:gas_burner}

Solids and liquid fuels can be modeled by specifying their relevant
properties via the {\ct MATL} namelist group. However, if you simply
want to specify a fire of a given heat release rate (HRR),
you need not specify any material properties. A specified fire is
basically modeled as the ejection of gaseous fuel
from a solid surface or vent. This is essentially a burner, with a
specified Heat Release Rate Per Unit Area, {\ct HRRPUA}, in units of
kW/m$^2$. For example
\begin{lstlisting}
&SURF ID='FIRE', HRRPUA=500. /
\end{lstlisting}
applies 500~kW/m$^2$ to any surface with the attribute
{\ct SURF\_ID='FIRE'}. See the discussion of time-dependent quantities
in Chapter~\ref{info:RAMP} to learn how to ramp the heat release rate up and down.

An alternative to {\ct HRRPUA} with the exact same functionality is {\ct MLRPUA}, except this parameter
specifies the Mass Loss Rate of fuel gas Per Unit Area in \si{kg/(m$^2$.s)}. Do not specify both
{\ct HRRPUA} and {\ct MLRPUA} on the same {\ct SURF} line.  Neither of them can be used if the model contains multiple reactions.



\subsection{Special Topic: A Radially-Spreading Fire}
\label{info:spread}

Sometimes it is desired that a fire spread radially at some specified rate. Rather than trying to obtain material properties to directly model the ignition and spread of the fire, you can specify the fire spread rate directly. First, you need to add a {\ct SURF} line with a specified heat release rate, {\ct HRRPUA}, and an optional time history parameter, {\ct RAMP\_Q} or {\ct TAU\_Q} (see Section \ref{info:RAMP_Time}). Then, you must specify {\ct XYZ} and {\ct SPREAD\_RATE} on either a {\ct VENT} or the same {\ct SURF} line. The fire is directed to start at the point {\ct XYZ} and spread radially at a rate of {\ct SPREAD\_RATE} (m/s). The optional ramp-up of the HRR begins at the time when the fire arrives at a given point. For example, the lines
\begin{lstlisting}
&SURF ID='FIRE', HRRPUA=500.0, RAMP_Q='fireramp' /
&RAMP ID='fireramp', T= 0.0, F=0.0 /
&RAMP ID='fireramp', T= 1.0, F=1.0 /
&RAMP ID='fireramp', T=30.0, F=1.0 /
&RAMP ID='fireramp', T=31.0, F=0.0 /
&VENT XB=0.0,5.0,1.5,9.5,0.0,0.0, SURF_ID='FIRE', XYZ=1.5,4.0,0.0, SPREAD_RATE=0.03 /
\end{lstlisting}
create a rectangular area via the {\ct VENT} line on which the fire starts at the point (1.5,4.0,0.0) and spreads outwards at a rate of 0.03~m/s. Each surface cell burns for 30~s as the fire spreads outward, creating a widening ring of fire. Note that the {\ct RAMP\_Q} is used to turn the burning on and off to simulate the consumption of fuel as the fire spreads radially. It should not be used to mimic a $t$-squared fire growth rate -- the whole point of the exercise is to mimic this curve in a more natural way. Eventually, the fire goes out as the ring grows past the boundary of the rectangle. Some trial and error is probably required to find the {\ct SPREAD\_RATE} that leads to a desired time history of the heat release rate.

If you desire that the fire spread over an area that is not confined to a flat plane, specify {\ct XYZ} and {\ct SPREAD\_RATE} on the {\ct SURF} line directly and then apply that {\ct SURF} line to the obstructions or particles over which you want the fire to spread. This technique can be useful for simulating the spread of fire through a cluttered space when the detailed properties of the materials are unknown, or when the uncertainties associated with modeling the pyrolysis of the solid fuels directly are too great.


If the starting time of the simulation, {\ct T\_BEGIN}, is not zero, be aware that the default start time of the radially spreading fire is {\ct T\_BEGIN}, not zero. This is also true of {\ct TAU\_Q}, but it is not true of {\ct RAMP\_Q}. Because this might be confusing, if you start the calculation at a time other than zero, do a quick test to ensure that the ramps or fire spread behave as expected.



\subsection{Solid Fuels that Burn at a Specified Rate}
\label{info:specified_burning}

Real objects, like furnishings, office equipment, and so on, are often difficult to describe via the {\ct SURF} and {\ct MATL} parameters. Sometimes the only information about a given object is its bulk thermal properties, its ``ignition'' temperature, and its subsequent burning rate as a function of time from ignition. For this situation, add lines similar to the following:
\begin{lstlisting}
&MATL ID                   = 'stuff'
      CONDUCTIVITY         = 0.1
      SPECIFIC_HEAT        = 1.0
      DENSITY              = 900.0 /

&SURF ID                   = 'my surface'
      COLOR                = 'GREEN'
      MATL_ID              = 'stuff'
      HRRPUA               = 1000.
      IGNITION_TEMPERATURE = 500.
      RAMP_Q               = 'fire_ramp'
      THICKNESS            = 0.01 /

&RAMP ID='fire_ramp', T=  0.0, F=0.0 /
&RAMP ID='fire_ramp', T= 10.0, F=1.0 /
&RAMP ID='fire_ramp', T=310.0, F=1.0 /
&RAMP ID='fire_ramp', T=320.0, F=0.0 /
\end{lstlisting}
An object with surface properties defined by {\ct 'my surface'} shall burn at a rate of 1000~kW/m$^2$ after a linear ramp-up of 10 s following its ``ignition'' when its surface temperature reaches 500~$^\circ$C. Burning shall continue for 5~min, and then ramp-down in 10~s. Note that the time {\ct T} in the {\ct RAMP} means time from ignition, not the time from the beginning of the simulation. Note also that now the ``ignition temperature'' is a surface property, not material property.

After the surface has ignited, the heat transfer into the solid is still calculated, but there is no coupling between the burning rate and the surface temperature. As a result, the surface temperature may increase too much. To account for the energy loss due to the vaporization of the solid fuel, {\ct HEAT\_OF\_VAPORIZATION} can be specified for the surface. For example, when using the lines below, the net heat flux at the material surface is reduced by a factor 1000~kJ/kg times the instantaneous burning rate.
\begin{lstlisting}
&SURF ID                   = 'my surface'
      COLOR                = 'GREEN'
      MATL_ID              = 'stuff'
      HRRPUA               = 1000.
      IGNITION_TEMPERATURE = 500.
      HEAT_OF_VAPORIZATION = 1000.
      RAMP_Q               = 'fire_ramp'
      THICKNESS            = 0.01 /
\end{lstlisting}
Finally, if you desire that the burning stop if the surface temperature drops below a specified value, set {\ct EXTINCTION\_TEMPERATURE} on the {\ct SURF} line. This value should be less than or equal to the \linebreak[4]{\ct IGNITION\_TEMPERATURE}.

The parameters {\ct HRRPUA}, {\ct IGNITION\_TEMPERATURE}, {\ct EXTINCTION\_TEMPERATURE}, and \linebreak[4]{\ct HEAT\_OF\_VAPORIZATION} are all telling FDS that you want to control the burning rate yourself, but you still want to simulate the heating up and ``ignition'' of the fuel. When these parameters appear on the {\ct SURF} line, they are acting in concert. If {\ct HRRPUA} appears alone, the surface will begin burning at the start of the simulation, like a piloted burner. The addition of an {\ct IGNITION\_TEMPERATURE} delays burning until your specified temperature is reached. The addition of {\ct HEAT\_OF\_VAPORIZATION} tells FDS to account for the energy used to vaporize the fuel. For any of these options, if a {\ct MATL} line is invoked by a {\ct SURF} line containing a specified {\ct HRRPUA}, then that {\ct MATL} ought to have only thermal properties. The {\ct MATL} line should have no reaction parameters, product yields, and so on, like those described in the previous sections. By specifying {\ct HRRPUA}, you are controlling the burning rate rather than letting the material pyrolyze based on the conditions of the surrounding environment. Also note that this simple model assumes that the solid acts like a typical {\em thermoplastic} material, i.e. it pyrolyzes near the surface leaving relatively little char.






\section{Complex Pyrolysis Models}
\label{info:solid_pyrolysis}

This section describes the parameters that describe the reactions that occur within solid
materials when they are burning. It is strongly recommended before reading this section that you read some background material on
solid phase pyrolysis, for example ``Thermal Decomposition of Polymeric Materials,'' by Witkowski, Stec, and Hull, or
``Flaming Ignition of Solid Fuels,'' by Torero, both of which are in the 5th edition of the
{\em SFPE Handbook of Fire Protection Engineering}.

\subsection{Reaction Mechanism}

A solid surface in FDS may consist of multiple layers with multiple material components per layer. The material components are described via {\ct MATL} lines and are specified on the {\ct SURF} line that describes the structure of the solid.  Each {\ct MATL} can undergo several reactions that may occur at different temperatures. It may not undergo any -- it may just heat up. However, if it is to change form via one or more reactions, designate the number of reactions with the integer {\ct N\_REACTIONS}. It is very important that you designate {\ct N\_REACTIONS} or else FDS will ignore all parameters associated with reactions. Note that experimental evidence of multiple reactions does not imply that a single material is undergoing multiple reactions, but rather that multiple material components are undergoing individual reactions at distinct temperatures.  Currently, the maximum number of reactions for each material is 10 and the chain of consecutive reactions may contain up to 20 steps.

For a given material, the $j$th reaction can produce other solid materials whose names are designated with \linebreak[4] {\ct MATL\_ID(i,j)}, and gas species whose names are designated with {\ct SPEC\_ID(i,j)}. Note that the index, $i$, runs from 1 to the number of material or gaseous species. This index does {\em not} correspond to the order in which the {\ct MATL} or {\ct SPEC} lines are listed in the input file. For a given reaction, the relative amounts of solid or gaseous products are input to FDS via the {\em yields}: {\ct NU\_MATL(i,j)} and {\ct NU\_SPEC(i,j)}, respectively. The yields are all zero by default. If {\ct NU\_MATL(i,j)} or {\ct NU\_SPEC(i,j)} is non-zero, then you {\em must} indicate what the solid residue is via {\ct MATL\_ID(j)}, the {\ct ID} of another {\ct MATL} that is also listed in the input file. Ideally, the sum of the yields should add to 1, meaning that the mass of the reactant is conserved. However, there are times when it is convenient to have the yields sum to something less than one. For example, the spalling or ablation of concrete can be described as a ``reaction'' that consumes energy but does not produce any ``product'' because the concrete is assumed to have either fallen off the surface in chunks or pulverized powder. The concrete's mass is not conserved {\em in the model} because it has essentially disappeared from that particular surface.

For consistency, the {\ct HEAT\_OF\_COMBUSTION(i,j)} can also be specified for each species, $i$, in each reaction, $j$. These values are used only if the corresponding heats of combustion for the gaseous species are greater than zero.  Note that {\ct HEAT\_OF\_COMBUSTION(i,j)} discussed here is not necessarily the same as the {\ct HEAT\_OF\_COMBUSTION} of the surrogate {\ct FUEL} used for gas phase combustion (e.g., {\ct 'PROPANE'}).  When the heats of combustion differ, the mass flux of the surrogate {\ct FUEL} in the gas phase is adjusted so that the correct heat release rate is attained.  This is further discussed in the next section.

In the example below, the pyrolysis of wood is included within a simulation that uses a finite-rate reaction instead of the default mixing-controlled model. Notice in this case that all of the gas species (except for the background nitrogen) are explicitly defined, and as a result, FDS needs to be told explicitly what gaseous species are produced by the solid phase reactions. In this case, 82~\% of the mass of wood is converted to gaseous {\ct 'PYROLYZATE'} and 18~\% is converted to solid {\ct 'CHAR'}.
\begin{lstlisting}
&SPEC ID = 'PYROLYZATE', MW=53.6 /
&SPEC ID = 'OXYGEN', MASS_FRACTION_0 = 0.23 /
&SPEC ID = 'WATER VAPOR' /
&SPEC ID = 'CARBON DIOXIDE' /

&MATL ID                    = 'WOOD'
EMISSIVITY            = 0.9
CONDUCTIVITY          = 0.2
SPECIFIC_HEAT         = 1.3
DENSITY               = 570.
N_REACTIONS           = 1
A(1)                  = 1.89E10
E(1)                  = 1.51E5
N_S(1)                = 1.0
MATL_ID(1,1)          = 'CHAR'
NU_MATL(1,1)          = 0.18
SPEC_ID(1:4,1)        = 'OXYGEN','WATER VAPOR','CARBON DIOXIDE','PYROLYZATE'
NU_SPEC(1:4,1)        = 0.82,0,0,0
HEAT_OF_REACTION(1)   = 430.
HEAT_OF_COMBUSTION(4,1) = 14500. /
\end{lstlisting}
Note that the indices associated with the parameters are not needed {\em in this case}, but they are shown to emphasize that, in general, there can be multiple reactions with corresponding kinetic parameters and products.

\subsection{Reaction Rates}
\label{sec:reaction_rates}

For each reaction that each material component undergoes you must specify kinetic parameters of the reaction rate. The general evolution equation for a material undergoing one or more reactions is:
\be
  \frac{\d Y_{{\rm s},i}}{\d t} = - \sum_{j=1}^{N_{{\rm r},i}} r_{ij} + \sum_{i'=1}^{N_{\rm m}} \sum_{j=1}^{N_{{\rm r},i'}} \nu_{{\rm s},i'j} \; r_{i'j} \quad (i' \neq i)
\label{rr_tot}
\ee
where
\be
  r_{ij} = A_{ij} \; Y_{{\rm s},i}^{n_{{\rm s},ij}} \; \exp \left(-\frac{E_{ij}}{R \, T_{\rm s}} \right) X_{\rm O_2}^{n_{{\rm O_2},ij}}
  \quad ; \quad Y_{{\rm s},i} = \left( \frac{\rho_{{\rm s},i}}{\rho_{\rm s}(0)} \right)
  % \max\left[0,T_{\rm s}-T_{thr,ij}\right]^{n_{t,ij}}
  \label{rr}
\ee
The term, $r_{ij}$, defines the rate of reaction at the temperature, $T_{\rm s}$, of the $i$th material undergoing its $j$th reaction. The second term on the right of the equation (\ref{rr_tot}) represents the contributions of other materials producing the $i$th material as a residue with a yield of $\nu_{{\rm s},i'j}$. This term is denoted by {\ct NU\_MATL(:,j)} on the $i'$-th {\ct MATL} line. $\rho_{{\rm s},i}$ is the density of the $i$th material component of the layer, defined as the mass of the $i$th material component divided by the volume of the layer.  $\rho_{\rm s}(0)$ is the initial density of the layer. Thus, $Y_{{\rm s},i}=\rho_{{\rm s},i}/\rho_{\rm s}(0)$ is a quantity that increases if the $i$th material component is produced as a residue of some other reaction, or decreases if the $i$th component decomposes.  If the layer is composed of only one material, then $\rho_{{\rm s},i}/\rho_{\rm s}(0)$ is initially 1. $n_{{\rm s},ij}$ is the reaction order and prescribed under the name {\ct N\_S(j)}, and is 1 by default. If the value of $n_{\rm s}$ is not known, it is a good starting point to assume it is 1.

The pre-exponential factor, $A_{ij}$, is prescribed under the name {\ct A(j)} on the {\ct MATL} line of the $i$th material, with units of s$^{-1}$. $E_{ij}$, the activation energy, is prescribed via {\ct E(j)} in units of J/mol. Remember that 1~kcal is 4,184~J, and be careful with factors of 1000. For a given reaction, specify both $A$ and $E$, or neither. Do not specify only one of these two parameters. Typically, these parameters only have meaning when both are derived from a common set of experiments, like TGA (thermogravimetric analysis).

The fourth term of the reaction rate equation (\ref{rr}) can be used to simulate oxidation reactions. If the heterogeneous reaction order $n_{{\rm O_2},ij}$ is greater than zero, the reaction rate is affected by the local oxygen volume fraction, $X_{\rm O_2}$. It is calculated from the gas phase (first grid cell) oxygen volume fraction $X_{\rm O_2,g}$ by assuming simultaneous diffusion and consumption so that the concentration profile is in equilibrium, and the concentration at depth $x$ is given by
\be
X_{\rm O_2}(x) = X_{\rm O_2,g}\exp(-x/L_{\rm g})
\ee
where $L_{\rm g}$ is the gas diffusion length scale. $n_{{\rm O_2},ij}$ is prescribed under the name {\ct N\_O2(j)} on the {\ct MATL} line of the $i$th material. It is zero by default. $L_{\rm g}$ is prescribed under the name {\ct GAS\_DIFFUSION\_DEPTH(j)}, and it is 0.001 m by default.

\subsubsection{Estimating Kinetic Parameters}

It is very important to keep in mind that the kinetic constants, $A$ and $E$, are not available for most real materials.  However, there is a way to model such materials using a simplified reaction scheme. The key assumption is that the material components can undergo only one reaction, at most. If, for example, the material undergoes three distinct reactions, there must be at least three material components, each of which undergoes one reaction. If there is an additional residue left over, then a fourth material component is needed.

In lieu of specifying $A$ and $E$, there are several parameters that can be used by FDS to derive effective values, the most important of which is the  {\ct REFERENCE\_TEMPERATURE} ($^\circ$C). To understand this parameter, consider the plot shown in Fig.~\ref{pyrolysis}. These curves represent the results of a hypothetical TGA experiment in which a single component material undergoes a single reaction that converts the solid into a gas. The Mass Fraction (blue curve) is the normalized density of the material ($Y_{\rm s}$) which decreases as the sample is slowly heated, in this case at a rate of 5~K/min. The Reaction Rate (green curve) is the rate of change of the mass fraction as a function of time ($-\d Y_{\rm s}/\d t$). Where this curve peaks is referred to in FDS as the {\ct REFERENCE\_TEMPERATURE}.\footnote{The term ``reference temperature'' is used simply to maintain backward compatibility with earlier versions of FDS.}  Note that the {\ct REFERENCE\_TEMPERATURE} is {\em not} the same as an ignition temperature, nor is it necessarily the surface temperature of the burning solid. Rather, it is simply the temperature at which the mass fraction of the material decreases at its maximum rate within the context of a TGA or similar experimental apparatus. Although you cannot specify an ignition temperature, you can specify a threshold temperature, see Section~\ref{info:threshold_temperature} for details.

The kinetic constants for component $i$ of a multi-component solid are given by\footnote{These formulas have been derived from an analysis that considers a first-order reaction. When using the proposed method, do not specify non-unity value for the reaction order {\ct N\_S} on the {\ct MATL} line.}:
\be
   E_{i,1} = \frac{ {\rm e} \, r_{{\rm p},i} }{ Y_{{\rm s},i}(0) } \, \frac{R \, T_{{\rm p},i}^2}{\dot{T}} \quad ; \quad
   A_{i,1} = \frac{ {\rm e} \, r_{{\rm p},i} }{ Y_{{\rm s},i}(0) } \, {\rm e}^{E/R \, T_{{\rm p},i}} \label{AandE}
\ee
where $T_{{\rm p},i}$ and $r_{{\rm p},i}/Y_{{\rm s},i}(0)$ are the reference temperature and rate, respectively. The {\ct REFERENCE\_RATE} is the reaction rate, in units of s$^{-1}$, at the given {\ct REFERENCE\_TEMPERATURE} divided by the mass fraction, $Y_{{\rm s},i}(0)$, of material in the original sample undergoing the reaction. For a single component, single reaction material, $Y_{{\rm s},1}(0)=1$. The {\ct HEATING\_RATE} ($\dot{T}$) is the rate at which the temperature of the TGA (or equivalent) test apparatus was increased. It is input into FDS in units of K/min (in the formula, it is expressed in K/s). Its default value is 5~K/min. In Fig.~\ref{pyrolysis}, the area under the green curve (Reaction Rate) is equal to the heating rate (in units of K/s).

\begin{figure}[ht]
\noindent
\begin{minipage}{0.5\textwidth}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/pyrolysis_1}
\end{minipage}
\hfill
\begin{minipage}{0.5\textwidth}
\begin{equation*}
   \frac{\d Y_{\rm s}}{\d t} = -A \, Y_{\rm s} \, \exp(-E/RT_{\rm s})   \quad \; \quad    Y_{\rm s}(0) =1
\end{equation*}
\begin{align*}
   T_{\rm p} &= 300 \; ^\circ\mathrm{C}  \\
   r_{\rm p} &= 0.002   \; \mathrm{s}^{-1}  \\
   \dot{T} &= 5 \; \mathrm{K/min} \\
   \nu_{\rm s} &= 0 \\
\end{align*}
\end{minipage}
\caption[Simple demonstration of the pyrolysis model]{The blue curve represents the normalized mass, $Y_{\rm s}=\rho_{\rm s}/\rho_{\rm s}(0)$, of a solid material
undergoing heating at a rate of 5~K/min. The green curve represents the reaction rate, $-\d Y_{\rm s}/\d t$. The ordinary differential equation that describes the transformation is shown at right. Note that the parameters $T_{\rm p}$, $r_{\rm p}$, and $\nu_{\rm s}$ represent the ``reference'' temperature,
reaction rate, and residue yield of the single reaction. From these parameters, values of $A$ and $E$ can be estimated using
the formulae in (\ref{AandE}). The full set of parameters for this case are listed in {\ct pyrolysis\_1.fds}.}
\label{pyrolysis}
\end{figure}

There are many cases where it is only possible to estimate the {\ct REFERENCE\_TEMPERATURE} ($T_{\rm p}$) of a particular reaction because micro-scale calorimetry data is unavailable. In such cases, an additional parameter can be specified to help fine tune the shape of the reaction rate curve, assuming some sort of measurement or estimate has been made to indicate at what temperature, and over what temperature range, the reaction takes place. The {\ct PYROLYSIS\_RANGE} ($\Delta T$) is the approximate width (in degrees Celsius or Kelvin) of the green curve, assuming its shape to be roughly triangular. Its default value is 80~$^\circ$C. Using these input parameters, an estimate is made of the peak reaction rate, $r_{{\rm p},i}$, with which $E_{i,1}$, then $A_{i,1}$, are calculated.
\be
   \frac{r_{{\rm p},i}}{Y_{{\rm s},i}(0)} = \frac{2 \, \dot{T}} {\Delta T} \, (1-\nu_{{\rm s},i}) \label{r_p}
\ee
The parameter, $\nu_{{\rm s},i}$, is the yield of solid residue.

When in doubt about the values of these parameters, just specify the {\ct REFERENCE\_TEMPERATURE}. Note that FDS will automatically calculate $A$ and $E$ using the above formulae. Do not specify $A$ and $E$ if you specify the \linebreak[3] {\ct REFERENCE\_TEMPERATURE}, and do not specify {\ct PYROLYSIS\_RANGE} if you specify {\ct REFERENCE\_RATE}. For the material decomposition shown in Fig.~\ref{pyrolysis}, the {\ct MATL} would have the form:
\begin{lstlisting}
&MATL ID                       = 'My Fuel'
      ...
      N_REACTIONS              = 1
      SPEC_ID(1,1)             = '...'
      NU_SPEC(1,1)             = 1.
      REFERENCE_TEMPERATURE(1) = 300.
      REFERENCE_RATE(1)        = 0.002
      HEATING_RATE(1)          = 5.
      HEAT_OF_COMBUSTION(1)    = ...
      HEAT_OF_REACTION(1)      = ... /
\end{lstlisting}
Note that the indices have been added to the reaction parameters to
emphasize the fact that these parameters are stored in arrays of
length equal to {\ct N\_REACTIONS}. If there is only one reaction, you
need not include the {\ct (1)}, but it is a good habit to get into.
Note also that if the default combustion model is used, you can denote that the reaction
produces fuel gas using the appropriate {\ct SPEC\_ID}.
Note also that the {\ct HEAT\_OF\_COMBUSTION} is the energy released
per unit mass of fuel gas that mixes with oxygen and combusts.  This
has nothing to do with the pyrolysis process, so why is it specified
here? The answer is that when using the default combustion model in FDS there is only one {\em gas phase}
reaction of fuel and oxygen, but there can be dozens of
different materials and dozens of {\em solid phase} reactions. To
ensure that the fuel vapors from different materials combust to
produce the proper amount of energy, it is very important to specify a
{\ct HEAT\_OF\_COMBUSTION} for each material. That way, the mass loss
rate of fuel gases is automatically adjusted so that the effective
mass loss rate multiplied by the single, global, gas phase heat of
combustion produces the expected heat release rate. This adjustment uses the value of {\ct HOC\_COMPLETE}, see Section~\ref{info:hoc_complete}, on the {\ct REAC} line.
If, for example, the {\ct HOC\_COMPLETE} specified on the {\ct REAC} line is twice that
specified on the {\ct MATL} line, the mass of contained within wall
cell will be decremented by that determined by the pyrolysis model,
but the mass added to gas phase would be reduced by 50~\%. A different
value of heat of combustion can be specified for each species, $i$, in each reaction, $j$, via the parameter {\ct HEAT\_OF\_COMBUSTION(i,j)}.

\subsubsection{Modeling Upholstered Furnishings}

The example input file called {\ct Fires/couch.fds} demonstrates a simple way to model upholstered furniture. In residential fires, upholstered furniture makes up a significant fraction of the combustible load. A single couch can generate several megawatts of energy and sometimes lead to compartment flashover. Modeling a couch fire requires a simplification of its structure and materials.  At the very least, we want the upholstery to be modeled as a layer of fabric covering polyurethane foam. We need the thermal properties of each, along with estimates of the ``reference'' temperatures as described above. The foam might be described as follows:
\begin{lstlisting}
&MATL ID                    = 'FOAM'
      SPECIFIC_HEAT         = 1.0
      CONDUCTIVITY          = 0.05
      DENSITY               = 40.0
      N_REACTIONS           = 1
      SPEC_ID               = 'FUEL'
      NU_SPEC               = 1.
      REFERENCE_TEMPERATURE = 350.
      HEAT_OF_REACTION      = 1500.
      HEAT_OF_COMBUSTION    = 30000. /
\end{lstlisting}
Note that these properties are completely made up.  Both the fabric and the foam decompose into fuel gases via single-step reactions. The fuel gases from each have different composition and heats of combustion. FDS automatically adjusts the mass loss rate of each so that the ``effective'' fuel gas is that which is specified on the {\ct REAC} line.  Figure~\ref{couch} shows the fire after 10~min.  Only the reaction zone of the fire is shown; the smoke is hidden so that you can see the fire progressing along the couch.

\begin{figure}[ht]
\includegraphics[width=\textwidth]{SCRIPT_FIGURES/couch_600}
\caption[Results of the {\ct couch} test case]{Output of {\ct couch} test case showing fire on the couch at 10 min.}
\label{couch}
\end{figure}


\subsection{Shrinking and swelling materials}
\label{info:shrink_swell}

Many practical materials change in thickness during the thermal reactions. For example:
\begin{itemize}
\item Non-charring materials will shrink as material is removed from the condensed phase to the gas phase.
\item Porous materials like foams would shrink when the material melts and forms a non-porous layer.
\item Some charring materials swell, i.e., get thicker, when a porous char layer is formed.
\item Intumescent fire protection materials would swell significantly, creating an insulating layer.
\end{itemize}
In FDS, the layer thickness is updated according to the ratio of the instantaneous material density and the density of the material in its pure form, i.e.,
the {\ct DENSITY} on the {\ct MATL} line. In cases involving several material components, the amount of swelling and shrinking is determined by the maximum and sum of these ratios, respectively. In mathematical terms, this means that in each time step the size of each condensed phase cell is changed according to the ratio $\delta$
\be
\delta =
   \begin{cases}
   \max_i\left(\frac{\rho_{{\rm s},i}}{\rho_i}\right) & \text{if } \max_i \left(\frac{\rho_{{\rm s},i}}{\rho_i}\right)\geq 1 \\
   \sum_i\left(\frac{\rho_{{\rm s},i}}{\rho_i}\right) & \text{if } \max_i \left(\frac{\rho_{{\rm s},i}}{\rho_i}\right)<1
   \end{cases}
\ee
For example, if the original material with a {\ct DENSITY} of 500~kg/m$^3$ is completely converted into a residue with a {\ct DENSITY} of 1000~kg/m$^3$, the thickness of the material layer will be half of the original.

You can prevent shrinking by setting {\ct ALLOW\_SHRINKING} to {\ct .FALSE.} on the {\ct MATL} line. You can prevent swelling by specifying
{\ct ALLOW\_SWELLING} to {\ct .FALSE.} on the {\ct MATL} line.  By default, these flags are true. Shrinking/swelling does not take place if any of the materials with non-zero density has the corresponding flag set to false.



\subsection{Multiple Solid Phase Reactions}

The solid phase reaction represented by Fig.~\ref{pyrolysis} is fairly simple -- a single, homogeneous material is
heated and gasified completely.
In general, real materials are not so simple. First, they consist of more than one material component, each of which can
react over a particular
temperature interval, and some of which leave behind a solid residue.
Some material components may even undergo multiple reactions that
form different residues, like woods that form various amounts of tar, char, and ash, depending on the rate of heating.
Figure~\ref{pyrolysis_2} demonstrates a more complicated material than the one previously described.
It is a hypothetical material that
contains 10~\% (by mass) water and 90~\% solid material. The water evaporates in the neighborhood of 100~$^\circ$C and the
solid pyrolyzes in the
neighborhood of 300~$^\circ$C, leaving 20~\% of its mass behind in the form of a solid residue. The full set of parameters for this case are listed in {\ct pyrolysis\_2.fds}.

\begin{figure}[ht]
\noindent
\begin{minipage}{0.5\textwidth}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/pyrolysis_2}
\end{minipage}
\hfill
\begin{minipage}{0.5\textwidth}
\footnotesize
\begin{align*}
   \frac{\d Y_{\rm s,1}}{\d t} &= -A_{1,1} \, Y_{\rm s,1} \, \exp(-E_{1,1}/RT_{\rm s})                  & Y_{\rm s,1}(0) &=0.1 \\
   \frac{\d Y_{\rm s,2}}{\d t} &= -A_{2,1} \, Y_{\rm s,2} \, \exp(-E_{2,1}/RT_{\rm s})                  & Y_{\rm s,2}(0) &=0.9 \\
   \frac{\d Y_{\rm s,3}}{\d t} &= -\nu_{{\rm s},2,1} \frac{\d Y_{\rm s,2}}{\d t}                        & Y_{\rm s,3}(0) &=0.0
\end{align*}
\begin{align*}
   T_{{\rm p},1,1} &= 100+273 \; \mathrm{K}        & T_{{\rm p},2,1}   &= 300+273 \; \mathrm{K} \\
   r_{{\rm p},1,1} &= 0.0016 \; \mathrm{s}^{-1}           & r_{{\rm p},2,1}   &= 0.0012 \; \mathrm{s}^{-1} \\
   \nu_{{\rm s},1,1} &= 0                          & \nu_{{\rm s},2,1} &= 0.2 \\
   \dot{T} &= 5 \; \mathrm{K/min} & &
\end{align*}
\end{minipage} \normalsize
\caption[A more complicated demonstration of the pyrolysis model]{The blue curve represents the combined mass fraction, $\sum Y_{\rm s,i}$, and the green curve the net reaction rate, $-\d/\!\d t(\sum Y_{\rm s,i})$, for a material that contains 10~\% water (by mass) that evaporates at a temperature of 100~$^\circ$C, and 90~\% solid material that pyrolyzes at 300~$^\circ$C, leaving a 20~\% (by mass) residue behind. Note that the numbered subscripts refer to the material component and the reaction, respectively. In this case, there are three material components, and the first two each undergo a single reaction. The third material component is formed as a residue of the reaction of the second material.
The system of ordinary differential equations that governs the transformation of the materials is shown at right.}
\label{pyrolysis_2}
\end{figure}




\subsection{The Heat of Reaction}

Equation~(\ref{rr}) describes the rate of the reaction as a function of temperature.  Most solid phase reactions require energy; that is, they are {\em endothermic}. The amount of energy consumed, per unit mass of reactant that is converted into reaction products, is specified by the {\ct HEAT\_OF\_REACTION(j)}. Technically, this is the enthalpy difference between the products and the reactant. A positive value indicates that the reaction is {\em endothermic}; that is, the reaction takes energy out of the system. Usually the {\ct HEAT\_OF\_REACTION} is accurately known only for simple phase change reactions like the vaporization of water. For other reactions, it must be determined empirically (e.g., by differential scanning calorimetry).


\subsection{Special Topic: The ``Threshold'' Temperature}
\label{info:threshold_temperature}

In FDS, the reaction rate expression in Eq.~(\ref{rr}) includes an optional term:
\be
  r_{ij} = A_{ij} \; Y_{{\rm s},i}^{n_{{\rm s},ij}} \; \exp \left(-\frac{E_{ij}}{R \, T_{\rm s}} \right) \;
  \max\left[0,S_{{\rm thr},ij}(T_{\rm s}-T_{{\rm thr},ij})\right]^{n_{{\rm t},ij}}
  \label{rr2}
\ee
$T_{{\rm thr},ij}$ is an optional ``threshold'' temperature that allows the definition of non-Arrhenius pyrolysis functions and ignition criteria, and is prescribed by {\ct THRESHOLD\_TEMPERATURE(j)}. $S_{{\rm thr},ij}$ is the ``threshold direction'' that allows the triggering of reaction when temperature gets ``above'' $T_{{\rm thr},ij}$ ($S_{{\rm thr},ij}=+1$) or ``below'' $T_{{\rm thr},ij}$ ($S_{{\rm thr},ij}=-1$). $n_{{\rm t},j}$ is prescribed under the name {\ct N\_T(j)} and $S_{{\rm thr},ij}$ under {\ct THRESHOLD\_SIGN}. By default, $T_{{\rm thr},ij}$ is -273.15 degrees Celsius, $n_{{\rm t},j}$ is zero and $S_{{\rm thr},ij}=+1$; thus, the last term of Equation~\ref{rr2} does not affect the pyrolysis rate. The term can be used to describe a threshold temperature for the pyrolysis reaction by setting $T_{{\rm thr},ij}$ and $n_{{\rm t},j}$ = 0. Then the term is equal to 0 at temperatures below $T_{{\rm thr},ij}$ and 1 at temperatures above.

The threshold temperature can be used to simulate simple phase change reactions, such as melting and freezing. To make the reaction rate controlled by available energy, i.e., {\em not} kinetics, another optional term should be included in the reaction rate formula
\be
  r_{ij} = A_{ij}\frac{1}{H_{{\rm r},ij}\Delta t} \max\left[0,S_{{\rm thr},ij}(T_{\rm s}-T_{{\rm thr},ij})\right]^{n_{{\rm t},ij}}
  \label{rr3}
\ee
This form of reaction rate can be implemented by setting a logical parameter {\ct PCR(j)=.TRUE.}. The pre-exponental factor $A_{ij}$ should then be given a value that is close or slightly smaller than the specific heat (\si{kJ/(kg.K)}) of the material mixture at phase change temperature.

The input file {\ct water\_ice\_water.fds} demonstrates the use of the ``threshold'' temperature. A small amount of liquid water at 10~$^\circ$C is cooled down to -10~$^\circ$C in 10~min, and then heated up again to 10~$^\circ$C. The concentration of the liquid water as a function of temperature is plotted in Fig.~\ref{water_ice_water_plot}. The cooling phase is indicated by the blue line and heating phase by the red line.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/water_ice_water}
\end{center}
\caption[Results of the {\ct water\_ice\_water} test case]{Freezing and melting of water.}
\label{water_ice_water_plot}
\end{figure}




\subsection{Liquid Fuels}
\label{info:liquid_fuels}

For a liquid fuel, the thermal properties are similar to those of a solid material, with a few exceptions. The evaporation rate of the fuel is governed by the mass transfer number (see FDS Technical Reference Guide for details). The properties of a liquid fuel are given on the {\ct MATL} line:
\begin{lstlisting}
&REAC FUEL               = 'ETHANOL'
      CO_YIELD           = 0.001
      SOOT_YIELD         = 0.008 /

&MATL ID                     = 'ETHANOL LIQUID'
      EMISSIVITY             = 1.
      NU_SPEC                = 1.
      SPEC_ID                = 'ETHANOL'
      HEAT_OF_REACTION       = 837
      CONDUCTIVITY           = 0.17
      SPECIFIC_HEAT          = 2.44
      DENSITY                = 794
      ABSORPTION_COEFFICIENT = 1140
      BOILING_TEMPERATURE    = 78.5 /

&SURF ID        = 'ETHANOL POOL'
      COLOR     = 'YELLOW'
      MATL_ID   = 'ETHANOL LIQUID'
      THICKNESS = 0.1 /
\end{lstlisting}
The inclusion of {\ct BOILING\_TEMPERATURE} on the {\ct MATL} line tells FDS to use its liquid pyrolysis model. It also automatically sets {\ct N\_REACTIONS=1}, that is, the only ``reaction'' is the phase change from liquid to gaseous fuel. Thus, {\ct HEAT\_OF\_REACTION} in this case is the latent heat of vaporization. The thermal conductivity, density and specific heat are used to compute the loss of heat into the liquid via conduction using the same one-dimensional heat transfer equation that is used for solids. Obviously, the convection of the liquid is important, but is not considered in the model. The {\ct ABSORPTION\_COEFFICIENT} denotes the absorption in depth of thermal radiation into the liquid. Liquids do not just absorb radiation at the surface, but rather over a thin layer near the surface. Its effect on the burning rate can be significant.

In this example, {\ct 'ETHANOL'} is a {\em known} species; that is, it is listed in Table~\ref{tab:gasspecies}. For this reason, you only need to specify its CO and soot yield. If it is not known, then you must furnish additional information. Section~\ref{user_defined_gas_species_props} contains details, but in brief, only the molecular weight of the gas species is of relevance for the liquid pool evaporation model.


\subsection{Fuel Burnout}

The thermal properties of a solid or liquid fuel determine the length of time for which it can burn. In general, the burnout time is a function of the mass loss rate, $\dot{m}''$, the density, $\rho_{\rm s}$, and the layer thickness, $\delta_{\rm s}$:
\be
   t_{\rm b} = \frac{\rho_{\rm s} \, \delta_{\rm s}}{\dm''}
\ee
However, each type of pyrolysis model handles fuel burnout in a slightly different way. These differences will be highlighted in the individual sections below.

\subsubsection{Solid Fuel Burnout When the Burning Rate is Specified}

If you {\em specify} the burning rate using {\ct HRRPUA} (Heat Release Rate Per Unit Area) or {\ct MLRPUA} (Mass Loss Rate Per Unit Area), the solid surface will continue to burn at the specified rate indefinitely with no fuel burnout. You may use {\ct RAMP\_Q} to stop the burning at a desired time. You can estimate this ``burnout time'' for a surface using the heat of combustion, $\Delta H$, material density, $\rho_{\rm s}$, material thickness, $\delta_{\rm s}$, and {\ct HRRPUA}, $\dq_{\rm f}''$:
\be
   t_{\rm b} = \frac{\rho_{\rm s} \, \delta_{\rm s} \, \Delta H}{\dq''_{\rm f}}
\ee
The burnout time is not calculated and applied automatically because there are instances where the underlying solid is not considered fuel; that is, the burning rate and duration are not determined by the composition of the solid surface.


\subsubsection{Solid Fuel Burnout When the Burning Rate is Not Specified}

If you use are using a pyrolysis model in which the {\ct MATL} lines have {\ct N\_REACTIONS} greater than or equal to 1, the burnout time of the pyrolyzing solid fuel is calculated automatically by FDS based on the layer {\ct THICKNESS}, component {\ct DENSITY}, and the calculated reactions rates of the materials.


\subsubsection{Liquid Fuel Burnout}

The burnout time of a liquid fuel is calculated automatically based on the liquid layer {\ct THICKNESS}, liquid {\ct DENSITY}, and the calculated burning rate.


\subsubsection{Special topic: Making Fuels Disappear}
\label{info:BURN_AWAY}
\label{box_burn_away1}
\label{box_burn_away2}
\label{box_burn_away3}
\label{box_burn_away4}
\label{box_burn_away5}
\label{box_burn_away6}
\label{box_burn_away_2D}
\label{box_burn_away_2D_residue}

If a burning object is to disappear from the simulation once it is consumed, set {\ct BURN\_AWAY=.TRUE.} on the corresponding {\ct SURF} line. The solid object disappears from the calculation cell by cell, as the mass contained within each solid cell is consumed either by the pyrolysis reactions or by the prescribed HRR. The following issues should be kept in mind when using {\ct BURN\_AWAY}:
\begin{itemize}
\item Use {\ct BURN\_AWAY} parameter cautiously. If an object has the potential of burning away, a significant amount of extra memory has to be set aside to store additional surface information as the mesh cells disappear.
\item If {\ct BURN\_AWAY} is prescribed, the {\ct SURF} should be applied to the entire object, not just a face of the object because it is unclear how to handle edges of solid obstructions that have different {\ct SURF\_ID}s on different faces.
\item If the volume of the obstruction changes because it has to conform to the uniform mesh, FDS does {\em not} adjust the burning rate to account for this as it does with various quantities associated with areas, like {\ct HRRPUA}.
\item A parameter called {\ct BULK\_DENSITY} (kg/m$^3$) can be applied to the {\ct OBST} rather than the {\ct SURF} line. This parameter is used to determine the {\em combustible} mass of the solid object. The calculation uses the user-specified object dimensions, not those of the mesh-adjusted object. This parameter over-rides all other parameters from which a combustible mass would be calculated. Note that without a {\ct BULK\_DENSITY} specified, the total amount of mass burned will depend upon the grid resolution. The use of the {\ct BULK\_DENSITY} parameter ensures a specific fuel mass per unit volume that is independent of the grid resolution. Note that in the event that the solid phase reaction involves the production of solid residue (like char or ash), the {\ct BULK\_DENSITY} refers to the mass of the solid that is converted to gas upon reaction.
\item The mass of the object is based on the densities of all material components ({\ct MATL}), but it is only consumed by mass fluxes of the {\em known} species. If the sum of the gaseous yields is less than one, it will take longer to consume the mass.
\end{itemize}
Simple examples demonstrating how solid fuels can be forced to disappear from the domain are labeled \linebreak[4] {\ct Fires/box\_burn\_away}. These are examples of a solid block of solid material that is pyrolyzed until it is completely consumed. The heat flux is generated by placing hot surfaces around the box. There is no combustion. In the first
example, {\ct box\_burn\_away1}, the released gas is ({\ct 'METHANE'}), and in the second example, {\ct box\_burn\_away2}, it is an additional species called {\ct 'GAS'}. In the third and fourth examples {\ct box\_burn\_away3} and {\ct box\_burn\_away4}, the released gas is fuel but the pyrolysis rate is specified. In the fourth case, the heat of combustion for the foam material is set different from that of the gas, with a ratio of 0.75. In the fifth example, {\ct box\_burn\_away2}, the first example is repeated using with {\ct N\_SIMPLE\_CHEMSITRY\_REACTIONS=2}. The results should match the first case as the creation of fuel should be based upon the total heat of combustion for {\ct 'METHANE'} and not the heat of combustion for the first reaction. The sixth case, {\ct box\_burn\_away6}, has two fuels with the second fuel defined with half the heat of combustion of the second. On the MATL input the two fuels are given equal {\ct NU} and are assigned the same {\ct HEAT\_OF\_COMBUSTION}. As a result, the second fuel will have twice as much mass in the gas phase.  The properties of the solid material were chosen simply to assure a quick calculation. The objective of the test is to
check that the released mass and the integrated burning rate are consistent with the material properties of the block. The block is 0.4~m on a side, with a density of 20~kg/m$^3$.  The integrated densities of the pyrolysis product gases (written to {\ct box\_burn\_away\#\_devc.csv}), as well as the integrated burning rate (written to {\ct box\_burn\_away\#\_hrr.csv}) at
the end of the 30~s calculation ought to be:
\be
(0.4)^3 \; \hbox{m}^3 \times 20 \; \hbox{kg/m}^3 = 1.28 \; \hbox{kg}
\ee
except for the fourth case, where the amount of released gas is affected by the ratio of heats of combustion
\be
0.75 \times 1.28 \; \hbox{kg}\; = 0.96 \; \hbox{kg}
\ee
The same case is tested in two dimensions ({\ct box\_burn\_away\_2D} and {\ct box\_burn\_away\_2D\_residue}). In the latter case, only half of the mass is converted to fuel, leaving behind a residue that is 50~\% of the original mass. The box is forced to burn away by setting the {\ct BULK\_DENSITY} to 10~kg/m$^3$. This is the {\em combustible} mass. These two cases exhibit a fictitious increase in solid mass when new unburned surfaces are exposed as entire mesh cells disappear. The increased mass is just an artifact of reporting the residual solid mass as the product of surface density and surface area. Both the final solid mass and the gaseous degradation products should match the expected values at the end of the simulation.

\begin{figure}[p]
	\begin{tabular*}{\textwidth}{lr}
		\includegraphics[width=3.2in]{SCRIPT_FIGURES/box_burn_away1} &
		\includegraphics[width=3.2in]{SCRIPT_FIGURES/box_burn_away2} \\
		\includegraphics[width=3.2in]{SCRIPT_FIGURES/box_burn_away3} &
		\includegraphics[width=3.2in]{SCRIPT_FIGURES/box_burn_away4} \\
		\includegraphics[width=3.2in]{SCRIPT_FIGURES/box_burn_away5} &
		\includegraphics[width=3.2in]{SCRIPT_FIGURES/box_burn_away6} \\
	\end{tabular*}
	\caption[Results of the {\ct box\_burn\_away} test cases]{Output of {\ct box\_burn\_away} test cases.}
	\label{box_burn_away}
\end{figure}


\begin{figure}
\begin{tabular*}{\textwidth}{lr}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/box_burn_away_2D} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/box_burn_away_2D_residue} \\
\end{tabular*}
\caption[Results of the {\ct box\_burn\_away\_2D} test cases]{Output of {\ct box\_burn\_away\_2D} test cases.}
\label{box_burn_away_2D_fig}
\end{figure}


\subsection{Solid Pyrolysis 3D (Beta)}
\label{info:pyro3d}

Pyrolysis may also be applied with 3D heat transfer.  To invoke the 3D pyrolysis model, set {\ct HT3D=T} on the {\ct SURF} line with a {\ct MATL\_ID} that specifies the kinetics parameters (see Sec.~\ref{sec:reaction_rates}) for details on kinetics parameters).  An example is given below:
\begin{lstlisting}
&SURF ID='PMMA SLAB 3D'
      MATL_ID='BLACKPMMA 3D'
      EXTERNAL_FLUX=50
      HT3D=T
      BURN_AWAY=T /
\end{lstlisting}
Since the 3D pyrolysis model does not have an internal ``thickness'' that shrinks from the bottom up, it is usually necessary to add {\ct BURN\_AWAY=T}.

By default, like the 1D model, the current 3D pyrolysis model uses a very simple form of mass transfer---any mass that is pyrolyzed is instantly transported to a surface cell to be injected into the gas phase.  Unless otherwise specified, the 3D solver sends the pyrolyzate to the \emph{nearest} wall cell ({\ct PYRO3D\_IOR=0}).  You can change this behavior by setting {\ct PYRO3D\_IOR} on the {\ct OBST} line.  The pyrolyzate is ejected via the nearest wall cell in the direction of the orientation index. For example, to send the gas to nearest cell in the vertical direction use something like this,
\begin{lstlisting}
&OBST XB=..., HT3D=T, PYRO3D_IOR=3, BULK_DENSITY=1100.,
      SURF_IDS='PMMA SLAB 3D','INSULATION','INSULATION' /
\end{lstlisting}

As an alternative to direct mass ejection, a diffusion approximation may be used to transport gas from the cell where it was generated to the surface of the solid.  To invoke this model, use
\begin{lstlisting}
&OBST XB=..., PYRO3D_MASS_TRANSPORT=T, .../ ! supersedes PYRO3D_IOR
\end{lstlisting}
\vskip-.5\baselineskip
At present, fuel gases are transported \emph{out} of the solid.  Other species, such as oxidizer, may transport into the solid.  The fuel gas diffusivity may be specified on the {\ct MATL} line using the array {\ct DIFFUSIVITY\_SPEC(:)} in the same order as {\ct SPEC\_ID}.  If no diffusivity is specified, then the molecular diffusivity of the gas is used.

\subsubsection*{Useful Outputs}
\label{sec:useful_outputs}

With the 3D pyrolysis model you no longer have to ``view'' output through {\ct DEVC}s only.  An {\ct SLCF} that passes through the {\ct OBST} may be viewed in Smokeview (use Show/Hide > Geometry > Obstacles > Hidden or Outline Only to view slices inside obstructions [toggle with ALT + O]).  The solid cell temperatures can be viewed using the gas phase output
\begin{lstlisting}
&SLCF PBY=..., QUANTITY='TEMPERATURE', CELL_CENTERED=T /
\end{lstlisting}

With 3D pyrolysis it is also useful to view the solid density, both in total and for individual components, and the solid-volume-to-cell-volume ratio:
\begin{lstlisting}
&SLCF PBY=..., QUANTITY='SOLID CELL DENSITY', CELL_CENTERED=T / total material density (omit MATL_ID)
&SLCF PBY=..., QUANTITY='SOLID CELL DENSITY', MATL_ID='CHAR', CELL_CENTERED=T /
&SLCF PBY=..., QUANTITY='SOLID CELL VOLUME RATIO', CELL_CENTERED=T /
\end{lstlisting}
To output the volumetric heat source term [\si{kW/m^3}] in the 3D heat transfer equation use
\begin{lstlisting}
&SLCF PBY=..., QUANTITY='SOLID CELL Q_S', CELL_CENTERED=T /
\end{lstlisting}
When using 3D mass transport, view the fuel gas density inside the solid using
\begin{lstlisting}
&SLCF PBY=..., QUANTITY='DENSITY', SPEC_ID='My FUEL', CELL_CENTERED=T /
\end{lstlisting}

All the above also work as {\ct DEVC} output, which does not require {\ct CELL\_CENTERED=T}.


\clearpage

\section{Thermal Degradation Model for Vegetation}

FDS contains a separate pyrolysis model that was developed specifically for vegetation~\cite{Porterie:2006,Morvan:CF2004,Houssami:2016}. The solid-phase thermal degradation process consists of three reactions:

\vspace{\baselineskip}

\noindent 1. Endothermic drying
\be
 {\rm Wet\ Vegetation} \rightarrow \frac{M}{1+M} \, {\rm H_2O} + \frac{1}{1+M} \, {\rm Dry\ Vegetation}
\ee

\noindent 2. Endothermic pyrolysis
\be
 {\rm Dry\ Vegetation} \rightarrow \chi_{\rm char} \, {\rm Char} + (1-\chi_{\rm char}) \, {\rm Fuel\ Gas}
\ee

\noindent 3. Exothermic char oxidation
\be
 {\rm Char} + \nu_{\rm O_2, char} \, {\rm O_2} \rightarrow (1+ \nu_{\rm O_2,char} - \chi_{\rm ash}) \, {\rm CO_2} + \chi_{\rm ash} \, {\rm Ash}
\ee
$M$ is the vegetation {\em moisture content} determined on a dry weight basis. $M$ is related to the vegetation mass fraction of water, $Y_{\rm w}$, via the relation:
\be
  Y_{\rm w} = \frac{M}{1+M}
\ee
$\chi_{\rm char}$ is the mass fraction of dry vegetation that is converted to char during pyrolysis;  $\nu_{\rm O_2,char}$ is the stoichiometric coefficient of oxygen;  and $\chi_{\rm ash}$ is the mass fraction of char that is converted to ash during char oxidation.

In the equations to follow, the subscript b denotes bulk quantities that are resolved on the computational grid. For example, the mass of dry vegetation per unit volume is denoted $\rho_{\rm b,dry}$ (kg/m$^{3}$).  In the notation of Mell~et~al.~\cite{Mell:2009}, $\rho_{\rm b,dry}=\langle m^{\prime\prime\prime}_{\rm dry}\rangle_{V_{\rm b}}$ where the angled brackets denote the explicit LES filtering over the grid cell volume $V_{\rm b}$. The initial total mass of vegetation per unit volume is $\rho_{\rm b,0}$.

The Arrhenius rate equations for drying, pyrolysis, and char oxidation are:
\begin{eqnarray}
  r_{\rm H_2O} &=& \left( \frac{\rho_{\rm b, H_2O}}{\rho_{\rm b,0}} \right)   \, A_{\rm H_2O} \, T_{\rm v}^{-\frac{1}{2}} \exp \left(-\frac{E_{\rm H_2O}}{R \, T_{\rm v}} \right)  \\[.1in]
  r_{\rm pyr}  &=& \left( \frac{\rho_{\rm b,dry}}{\rho_{\rm b,0}}   \right)   \, A_{\rm pyr} \, \exp \left({-\frac{E_{\rm pyr}}{R \, T_{\rm v}}} \right)  \\[.1in]
  r_{\rm char} &=& \left( \frac{\rho_{\rm b,char}}{\rho_{\rm b,0}}  \right)^0 \, A_{\rm char} \,  \exp \left( -\frac{E_{\rm char}}{R \, T_{\rm v}} \right) \,
  \frac{ \rho_{\rm g}\, Y_{\rm O_2}\, \sigma_{\rm v}\, \beta_{\rm v}\, (1+\beta_{\rm char}\sqrt{\RE_{\rm v}}) }{\nu_{\rm O_2,char} \, \rho_{\rm b,0}}
\end{eqnarray}
where $T_{\rm v}$ is the temperature of the vegetation. The default values of the kinetic constants are given in Table~\ref{tab:veg_kinetics}. The Reynolds number is $\RE_{\rm v} = \rho_{\rm g} D_{\rm v} / \mu $ with $D_{\rm v} = 4/\sigma_{\rm v}$ for a cylinder, where $\sigma_{\rm v}$ is the surface area to volume ratio of the cylinder. $\beta_{\rm v}$ is the {\em packing ratio}; that is, the ratio of the vegetation volume to the overall volume containing the vegetation. The term containing $\RE_{\rm v}$ is included to account for the oxygen blowing effects on char oxidation and the constant $\beta_{\rm char}$ is equal to 0.2 by default, which is the value used by Porterie~et~al.~\cite{Porterie:2006}.

\begin{table}[!ht]
\caption[Default vegetation kinetic constants]{Default vegetation kinetic constants (from Porterie et al.~\cite{Porterie:2006})}
\vspace{0.1in}
\label{tab:veg_kinetics}
\begin{center}
\begin{tabular}{|l|l|}
\hline
Constant                        &   Default Value  \\ \hline \hline
$A_{\rm H_2O}$ ($\sqrt{K}$/s )  & 600,000          \\ \hline
$E_{\rm H_2O}$ (J/mol)          & 48,200           \\ \hline
$A_{\rm pyr}$ (1/s)             & 36,300           \\ \hline
$E_{\rm pyr}$ (J/mol)           & 60,300           \\ \hline
$A_{\rm char}$ (m/s)            & 430              \\ \hline
$E_{\rm char}$ (J/mol)          & 74,800           \\ \hline
$\nu_{\rm O_2,char}$            & 1.65             \\ \hline
\end{tabular}
\end{center}
\end{table}

The equation governing the temperature of a thermally thin fuel element is
\be
\label{eq:Tv_thermally_thin}
\rho_{\rm b}\ c_{\rm p,v} \frac{dT_{\rm v}}{dt} = -\rho_{\rm b,0} \left( \Delta{\rm h_{vap}}\ r_{\rm H_2O} + \Delta {\rm h_{pyr}}\ r_{\rm pyr} + \alpha_{\rm char}\ \Delta{\rm h_{char}}\ r_{\rm char} + \langle \nabla \cdot{\mathbf{q}}^{\prime\prime}_{\rm c,b}\rangle_{\rm V_b} + \langle \nabla \cdot{\mathbf{q}}^{\prime\prime}_{\rm r,b}\rangle_{\rm V_b} \right)
\ee
The first three terms on the right-hand-side are, respectively, endothermic drying, endothermic pyrolysis, exothermic char oxidation. The non-dimensional weighting parameter, $\alpha_{\rm char}$, is the fraction of the heat generated by heterogeneous char oxidation that is deposited in the fuel element and (1-$\alpha_{\rm char}$) in the gas phase. By default, $\alpha_{\rm char}$ = 0.5, which has been used by others (e.g., Porterie~et~al.~\cite{Porterie:2006}). The fourth and fifth terms on the right-hand-side of Eq.~(\ref{eq:Tv_thermally_thin}) are the bulk contributions of convective and radiative heat transfer, respectively~\cite{Mell:2009}. The heats in Eq.~(\ref{eq:Tv_thermally_thin}) are $\Delta{\rm h_{vap}} = 2259$~kJ/kg;  $\Delta{\rm h_{pyr}} = 418$~kJ/kg~\cite{Morvan:CF2001}; $\Delta{\rm h_{char}} = -32000$~kJ/kg~\cite{Dahale:2013}.

In the condensed phase model, the bulk density and specific heat have contributions from dry virgin vegetative fuel, char, ash, and moisture:
\begin{eqnarray}
\rho_{\rm b} &=& \rho_{\rm b,dry} + \rho_{\rm b,char} + \rho_{\rm b,ash} + \rho_{\rm b,H_2O} \\[.1in]
{\rm c_{\rm p,v}} &=& \frac{\rho_{\rm b,dry}\ {\rm c_{p,dry}} + \rho_{\rm b,char}\ {\rm c_{p,char}} + \rho_{\rm b,ash}\ {\rm c_{p,ash}} + \rho_{\rm b,H_2O}\ {\rm c_{p,H_2O}}}{\rho_{\rm b}}
\end{eqnarray}
where, initially, $\rho_{\rm b,H_2O} = M_{\rm dw}\ \rho_{\rm b, dry}$. The specific heats (J kg$^{-1}$ K$^{-1}$) in the equations above are
\begin{eqnarray}
c_{\rm p, dry} &=& 10 + 3.7 \, T_{\rm v}~~~ ({\rm Ritchie~et~al.~\cite{Ritchie:1}})  \\[.1in]
c_{\rm p, char} &=& 420 + 2.09 \, T_{\rm v} + 6.85 \times 10^{-4} \, T^2_{\rm v} ~~~({\rm Park~et~al.~ 2010}) \\[.1in]
c_{\rm p, ash} &=& 1244 \, (T_{\rm v} / 300)^{0.315}~~~({\rm Lautenberger~et~al.~\cite{GPyro:FSJ}}) \\[.1in]
c_{\rm p,H_2O} &=& 4190
\end{eqnarray}
The rate of change of the total vegetative fuel mass is
\be
\frac{\d}{\d t} \left( \frac{\rho_{\rm b}}{\rho_{\rm b,0}} \right) = -r_{\rm H_2O} - (1 - \chi_{\rm char}) \, r_{\rm pyr} - (1-\chi_{\rm ash}) \, r_{\rm char}
\ee
The rate of change for the components of the vegetative mass during thermal degradation are:
\begin{eqnarray}
\frac{\d}{\d t} \left( \frac{\rho_{\rm b,H_2O}}{\rho_{\rm b,0}} \right) &=& -r_{\rm H_2O} \\[.1in]
\frac{\d}{\d t} \left( \frac{\rho_{\rm b,dry}}{\rho_{\rm b,0}} \right) &=& -r_{\rm dry}  \\[.1in]
\frac{\d}{\d t} \left( \frac{\rho_{\rm b,char}}{\rho_{\rm b,0}} \right) &=& -\chi_{\rm char}\ r_{\rm pyr} - r_{\rm char}
\end{eqnarray}
Gaseous products created during the thermal degradation process are water vapor (during drying), fuel vapor (during pyrolysis), and CO$_2$ (during char oxidation). The source terms (kg m$^{-3}$ s$^{-1}$) for these species are, respectively, $\rho_{\rm b,0} \, r_{\rm H_2O}$, $(1-\chi_{\rm char}) \, \rho_{\rm b,0} \, r_{\rm pyr}$, and  $(1+\nu_{\rm O_2,char} - \chi_{\rm ash}) \, \rho_{\rm b,0} \, r_{\rm char}$. In addition, the char oxidation process consumes oxygen in the gas phase at a rate of $-\nu_{\rm O_2,char} \, \rho_{\rm b,0} \, r_{\rm char}$.

Figure~\ref{vege_inputs} includes sample input lines demonstrating how the vegetation model can be applied to particles that represent pine needles that are 1~mm in diameter and 5~cm long. Note that each {\ct MATL} line contains the flag {\ct VEGETATION=.TRUE.} to indicate that the special vegetation model is to be invoked. All parameters described above must be explicitly specified in the input file---there are no hard-wired default values.

\begin{figure}[p]
\begin{lstlisting}
&PART ID='pine needles', SURF_ID='vegetation', STATIC=.TRUE. /

&SURF ID = 'vegetation'
      MATL_ID = 'WET VEGETATION'
      THICKNESS = 0.0005
      LENGTH = 0.05
      GEOMETRY = 'CYLINDRICAL' /

&MATL ID = 'WET VEGETATION'
      VEGETATION = .TRUE.
      DENSITY = 586.
      CONDUCTIVITY = 0.1
      SPECIFIC_HEAT = 2.0
      A = 600000.
      E = 48200.
      N_T = -0.5
      NU_SPEC = 0.123
      SPEC_ID = 'WATER VAPOR'
      NU_MATL = 0.877
      MATL_ID = 'DRY VEGETATION'
      HEAT_OF_REACTION = 2259. /

&MATL ID = 'DRY VEGETATION'
      VEGETATION = .TRUE.
      DENSITY = 514.
      CONDUCTIVITY = 0.1
      SPECIFIC_HEAT = 2.0
      A = 36300.
      E = 60300.
      NU_MATL = 0.26
      MATL_ID = 'CHAR'
      NU_SPEC = 0.74
      SPEC_ID = 'CELLULOSE'
      HEAT_OF_REACTION = 418. /

&MATL ID = 'CHAR'
      VEGETATION = .TRUE.
      DENSITY  = 134.
      CONDUCTIVITY = 0.1
      SPECIFIC_HEAT = 2.0
      N_S = 0.
      NU_O2 = 1.65
      BETA_CHAR = 0.2
      A = 430.
      E = 74800.
      NU_MATL = 0.5
      MATL_ID  = 'ASH'
      NU_SPEC = 2.15
      SPEC_ID = 'CARBON DIOXIDE'
      HEAT_OF_REACTION= -32000. /

&MATL ID = 'ASH'
      VEGETATION = .TRUE.
      DENSITY = 67.
      CONDUCTIVITY = 0.1
      SPECIFIC_HEAT = 2.0 /
\end{lstlisting}
\caption[Input parameters describing vegetation]{Input parameters describing vegetation.}
\label{vege_inputs}
\end{figure}



\section{Testing Your Pyrolysis Model}
\label{solid_phase_verification}

The {\ct SURF} and {\ct MATL} lines describing the pyrolysis of real materials consist of a combination of empirical and fundamental properties, often originating from different sources. How do you know that the various property values and the associated thermo-physical model in FDS constitute an appropriate description of the solid? For a full-scale simulation, it is hard to untangle the uncertainties associated with the gas and solid phase routines. However, you can perform a simple check of any set of solid phase model by essentially turning off the gas phase.  In the following sections, guidance is provided on how to perform a quick simulation of the cone calorimeter and bench-scale measurements like thermal gravimetric analysis (TGA), differential scanning calorimetry (DSC), and micro-combustion calorimetry (MCC).

\subsection{Simulating the Cone Calorimeter}

This section describes how to set up a simple model of the cone calorimeter or other similar apparatus. This is not a full 3-D simulation of the apparatus, but rather a 1-D simulation of the solid phase degradation under an imposed external heat flux. You can literally create a model of the cone heater and sample holder in FDS to simulate the coupling of gas and solid phase phenomena, but before even attempting this, it is worthwhile to perform a quick simulation like the one described here to test the solid phase model only.
\begin{enumerate}
\item Create a trivially small mesh, just to let FDS run. Since the gas phase calculation is essentially being shut off, you just need three cells in each direction ({\ct IJK=3,3,3}) for the pressure solver to function properly.
\item On the {\ct MISC} line, set {\ct SOLID\_PHASE\_ONLY=.TRUE.} to turn off all gas phase computation and speed up the simulation.
\item Create {\ct SPEC} lines to list any gas species created in the pyrolysis process. Do not specify a reaction using a {\ct REAC} line, as there is no gas phase combustion allowed.
\item On the {\ct TIME} line, set {\ct WALL\_INCREMENT=1} to force FDS to update the solid phase every time step (normally it does this every other time step), and set {\ct DT} to a value that is appropriate for the solid phase calculation. Since there is no gas phase calculation that will limit the time step, it is best to control this yourself.
\item Generate {\ct MATL} lines, plus a single {\ct SURF} line, as you normally would, except add {\ct EXTERNAL\_FLUX} to the {\ct SURF} line. This is simply a ``virtual'' source that heats the solid. Think of this as a perfect radiant panel or conical heating unit. You can control the {\ct EXTERNAL\_FLUX} using either {\ct TAU\_EF} or {\ct RAMP\_EF}. This is useful if you want to ramp up the heat flux following ignition to account for the additional radiation from the flame. See Section~\ref{info:RAMP_Time} for more details about ramps.
\item Set an {\ct ASSUMED\_GAS\_TEMPERATURE} ($^\circ$C, default {\ct TMPA}) and optionally a \linebreak[4]{\ct HEAT\_TRANSFER\_COEFFICIENT} (kW/(m$^2 \cdot$K)) on the {\ct SURF} line, allowing you to control the convective heat flux from gas to surface and vice versa.
\item Assign the {\ct SURF\_ID} to a {\ct VENT} that spans the bottom of the computational domain. Create {\ct OPEN} vents on all other faces of the computational domain.
\item Add solid phase output devices to the solid surface, like {\ct 'WALL TEMPERATURE'}, {\ct 'NET HEAT FLUX'}, {\ct 'GAUGE HEAT FLUX'}, and {\ct 'WALL THICKNESS'}. Use these to track the condition of the solid as a function of time. The generation rate of the various gases is output via the quantity {\ct 'MASS FLUX'} along with the appropriate {\ct SPEC\_ID}. Do not specify the quantity {\ct 'BURNING RATE'} because FDS assumes that this is specific for fuel gas, and in this exercise there is no fuel gas.
\end{enumerate}
Compare your results to measurements made in a bench-scale device, like the cone calorimeter. Keep in mind, however, that the calculation and the experiment are not necessarily perfectly matched. The calculation is designed to eliminate uncertainties related to convection, combustion, and apparatus-specific phenomena. Below is an FDS input file that demonstrates how you can test a candidate pyrolysis model by running very short calculations. The simulation only involves the solid phase model. Essentially, the gas phase calculation is shut off except for the imposition of a 50~kW/m$^2$ ``external'' heat flux. The solid in this example is a 8.5~mm thick slab of PMMA. For more details, see the FDS Validation Guide under the heading ``FAA Polymers.''
\begin{lstlisting}
&HEAD CHID='pmma_example', TITLE='Black PMMA at 50 kW/m2' /
&MESH IJK=3,3,3, XB=-0.15,0.15,-0.15,0.15,0.0,0.3 /
&TIME T_END=600., WALL_INCREMENT=1, DT=0.05 /
&MISC SOLID_PHASE_ONLY=.TRUE. /
&SPEC ID='METHANE' /
&MATL ID='BLACKPMMA'
      ABSORPTION_COEFFICIENT=2700.
      N_REACTIONS=1
      A(1) = 8.5E12
      E(1) = 188000
      EMISSIVITY=0.85
      DENSITY=1100.
      SPEC_ID='METHANE'
      NU_SPEC=1.
      HEAT_OF_REACTION=870.
      CONDUCTIVITY = 0.20
      SPECIFIC_HEAT = 2.2
&SURF ID='PMMA SLAB'
      COLOR='BLACK'
      BACKING='INSULATED'
      MATL_ID='BLACKPMMA'
      THICKNESS=0.0085
      EXTERNAL_FLUX=50 /
&VENT XB=-0.05,0.05,-0.05,0.05,0.0,0.0, SURF_ID = 'PMMA SLAB' /
&DUMP DT_DEVC=5. /
&DEVC XYZ=0.0,0.0,0.0, IOR=3, QUANTITY='WALL TEMPERATURE', ID='temp' /
&DEVC XYZ=0.0,0.0,0.0, IOR=3, QUANTITY='MASS FLUX', SPEC_ID='METHANE', ID='MF' /
&DEVC XYZ=0.0,0.0,0.0, IOR=3, QUANTITY='WALL THICKNESS',   ID='thick' /
&TAIL /
\end{lstlisting}


\subsection{Simulating Bench-scale Measurements like the TGA, DSC, and MCC}
\label{info:TGA_DSC_MCC}

There are a number of techniques to measure the thermo-physical properties of a solid material. Most of these involve heating a very small sample at a relatively slow, linear rate. In this way, thermal conduction is minimized and the sample can be considered thermally-thin. FDS has a special feature that mimics thermogravimetric analysis (TGA), differential scanning calorimetry (DSC), and micro-combustion calorimetry (MCC) measurements. To use it, set up your input file as you normally would. Then, add the flag {\ct TGA\_ANALYSIS=.TRUE.} to the {\ct SURF} line you want to analyze. You can only analyze one {\ct SURF} line at a time. Optionally, you can specify {\ct TGA\_HEATING\_RATE} (K/min) and {\ct TGA\_FINAL\_TEMPERATURE} ($^\circ$C) to indicate the linear heating rate and the final temperature of the sample. The default values are 5~K/min and 800~$^\circ$C. The initial temperature is {\ct TMPA}. Note that this feature is only appropriate for a {\ct SURF} line that describes a thermally-thick sample consisting of a single layer with multiple reacting components. For example, the following {\ct SURF} line describes a material that consists of three components:
\begin{lstlisting}
&SURF ID = 'Cable Insulation'
      TGA_ANALYSIS = .TRUE.
      TGA_HEATING_RATE = 60.
      THICKNESS = 0.005
      MATL_ID(1,1) = 'Component A',
      MATL_ID(1,2) = 'Component B',
      MATL_ID(1,3) = 'Component C',
      MATL_MASS_FRACTION(1,1:3) = 0.26,0.33,0.41 /
\end{lstlisting}
The two {\ct TGA} entries will force FDS to perform a numerical version of the TGA, DSC and MCC measurements. The {\ct THICKNESS} and other boundary conditions on the {\ct SURF} line will be ignored. After running the analysis, which only takes a second or two, FDS will then shut down without running the actual simulation. To run the simulation, either remove the {\ct TGA} entries or set {\ct TGA\_ANALYSIS} to {\ct .FALSE.}

The result of the {\ct TGA\_ANALYSIS} is a single comma-delimited file called {\ct CHID\_tga.csv}. The first and second columns of the file consist of the time and sample temperature. The third column is the normalized sample mass; that is, the sample mass divided by its initial mass. The following columns list the mass fractions of the individual material components. The next column is the total mass loss rate, in units of s$^{-1}$, followed by the mass loss rates of the individual material components. The next column is the heat release rate per unit mass of the sample in units of W/g, typical of an MCC measurement. The final column is the heat absorbed by the sample normalized by its mass, also in units of W/g, typical of a DSC measurement. Results for a typical analysis of wood are shown in Fig.~\ref{tga_results}. In this case, a sample of wood containing about 10~\% water by mass heats up and undergoes three reactions, including the evaporation of water. Note that the TGA plots include both fuel and water vapor, while the MCC results only show fuel.

Details of the output quantities are discussed in Section~\ref{info:material_components}. Further details on these measurement techniques and how to interpret them are found in the FDS Verification Guide~\cite{FDS_Verification_Guide}.

\begin{figure}[ht]
\begin{tabular*}{\textwidth}{lr}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/tga_analysis_mass} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/tga_analysis_mass_components} \\
\includegraphics[width=3.2in]{SCRIPT_FIGURES/tga_analysis_mlr} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/tga_analysis_mlr_components} \\
\includegraphics[width=3.2in]{SCRIPT_FIGURES/tga_analysis_mcc} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/tga_analysis_dsc}
\end{tabular*}
\caption[Sample results of a {\ct tga\_analysis}]{Sample results of a {\ct tga\_analysis}.}
\label{tga_results}
\end{figure}







\chapter{Ventilation}

This chapter explains how to model a ventilation system. There are two ways to do this. First, if you only want to specify air flow rates into and out of
compartments, read Section~\ref{info:Velocity_BC} for a description of simple velocity boundary conditions. However, if you want to
model the entire HVAC system, read Section~\ref{info:HVAC}.


\section{Simple Vents, Fans and Heaters}
\label{info:Velocity_BC}

The ventilation system of individual compartments within a building is described using velocity {\em boundary conditions}. For example, fresh air can be blown into, and smoke can be drawn from, a compartment by specifying a velocity in the {\em normal} direction to a solid surface. However, there are various other facets of velocity boundary conditions that are described below.

\subsection{Simple Supply and Exhaust Vents}
\label{volume_flow_1}
\label{volume_flow_2}

The easiest way to describe a supply or exhaust fan is to specify a {\ct VENT} on a solid surface, and designate a {\ct SURF\_ID} with some form of specified velocity or volume flow rate. The normal component of velocity is usually specified directly via the parameter {\ct VEL}. If {\ct VEL} is negative, the flow is directed {\em into} the computational domain, i.e., a supply vent. If {\ct VEL} is positive, the flow is drawn {\em out of} the domain, i.e., an exhaust vent. For example, the lines
\begin{lstlisting}
&SURF ID='SUPPLY', VEL=-1.2, COLOR='BLUE' /
&VENT XB=5.0,5.0,1.0,1.4,2.0,2.4, SURF_ID='SUPPLY' /
\end{lstlisting}
create a {\ct VENT} that {\em supplies} air at a velocity of 1.2~m/s through an area of nominally 0.16~m$^2$, depending on the realignment of the {\ct VENT} onto the FDS mesh. Regardless of the orientation of the plane $x=5$, the flow will be directed {\em into} the room because of the sign of {\ct VEL}. In this example the {\ct VENT} may not be exactly 0.16~m$^2$ in area because it may not align exactly with the computational mesh. If this is the case then {\ct VOLUME\_FLOW} can be prescribed instead of {\ct VEL}. The units are m$^3$/s. If the flow is entering the computational domain, {\ct VOLUME\_FLOW} should be a negative number, the same convention as for {\ct VEL}. Note that a {\ct SURF} with a {\ct VOLUME\_FLOW} prescribed can be invoked by either a {\ct VENT} or an {\ct OBST}, but be aware that in the latter case, the resulting velocity on the face or faces of the obstruction will be given by the specified {\ct VOLUME\_FLOW} divided by the area of that particular face. For example:
\begin{lstlisting}
&SURF ID='SUPPLY', VOLUME_FLOW=-5.0, COLOR='GREEN' /
&OBST XB=..., SURF_ID6='BRICK','SUPPLY','BRICK','BRICK','BRICK','BRICK' /
\end{lstlisting}
dictates that the forward $x$-facing surface of the obstruction is to have a velocity equal to 5~m$^3$/s divided by the area of the face (as approximated within FDS) flowing into the computational domain.

Note that {\ct VEL} and {\ct VOLUME\_FLOW} should not be specified on the same {\ct SURF} line.  The choice depends on whether an exact velocity is desired at a given vent, or whether the given volume flow is desired.

Note also that if the {\ct VENT} or {\ct OBST} crosses mesh boundaries, the specified {\ct VOLUME\_FLOW} will be recomputed in each mesh so that the desired volume flow is achieved. This was not the case in FDS version 6.3 and earlier. The sample cases called {\ct volume\_flow\_1.fds} and {\ct volume\_flow\_2.fds} in the {\ct Flowfields} folder demonstrate that a {\ct VENT} or an {\ct OBST} can be divided among several meshes. In both cases, air is drawn from a 1~m by 1~m by 1~m box at a rate of 0.01~m$^3$/s. These cases also ensure that the {\ct VENT} or {\ct OBST} need not be aligned with the mesh to yield the desired flow rate. Figure~\ref{volume_flow} displays the volume flow drawn though an {\ct OPEN} boundary on an opposite face of the box with either a {\ct VENT} (left) or {\ct OBST} (right) with a specified volume flow.

\begin{figure}[!ht]
\begin{tabular*}{\textwidth}{lr}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/volume_flow_1} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/volume_flow_2}
\end{tabular*}
\caption[Results of the {\ct volume\_flow} test cases]{Flow rate of air drawn through a unit cube via a {\ct VENT} (left) and {\ct OBST} (right) with specified {\ct VOLUME\_FLOW}.}
\label{volume_flow}
\end{figure}



\subsection{Total Mass Flux}

\label{info:MASS_FLUX_TOTAL}

Most often, you specify a simple supply or exhaust vent by setting either a normal velocity or volume flux at a solid surface. However, you may wish to control the total mass flow rate per unit area (\si{kg/(m$^2$.s)}) via the parameter {\ct MASS\_FLUX\_TOTAL}. This parameter uses the same sign convention as {\ct VEL} above.  In fact, the value entered for {\ct MASS\_FLUX\_TOTAL} is converted internally into a velocity boundary condition whose value for an outflow is adjusted based on the local density. Note that {\ct MASS\_FLUX\_TOTAL} should only be used for an outflow boundary condition; for inflow use {\ct MASS\_FLUX} which is discussed in Section~\ref{info:MASS_FLUX}.


\subsection{Heaters}

You can create a simple heating vent by changing the temperature of the incoming air
\begin{lstlisting}
&SURF ID='BLOWER', VEL=-1.2, TMP_FRONT=50. /
\end{lstlisting}
The {\ct VENT} with {\ct SURF\_ID='BLOWER'} would blow 50~$^\circ$C air at 1.2 m/s into the flow domain. Making {\ct VEL} positive would suck air out, in which case {\ct TMP\_FRONT} would not be necessary.

Note that if {\ct HRRPUA} or solid phase reaction parameters are specified, no velocity should be prescribed. The combustible gases are ejected at a velocity computed by FDS.



\subsection{Louvered Vents}
\label{info:louvers}
\label{tangential_velocity}

Most real supply vents are covered with some sort of grill or louvers which act to redirect, or {\em diffuse}, the incoming air stream. It is possible to mimic this effect, to some extent, by prescribing both a normal and the tangential components of the flow. The normal component is specified with {\ct VEL} as described above. The tangential is prescribed via a pair of real numbers {\ct VEL\_T} representing the desired tangential velocity components in the other two coordinate directions ($x$ or $y$ should precede $y$ or $z$). For example, the line in the example case {\ct Flowfields/tangential\_velocity.fds}
\begin{lstlisting}
&SURF ID='LOUVER', VEL=-2.0, VEL_T=3.0,0.0, TAU_V=5., COLOR='GREEN' /
\end{lstlisting}
is a boundary condition for a louvered vent that pushes air into the space with a normal velocity of 2~m/s and a tangential velocity of 3~m/s in the first of the two tangential directions. Note that the negative sign of the normal component of velocity indicates that the fluid is injected into the computational domain. The tangential velocity of 3~m/s indicates that the flow is in the positive $y$ direction. Both the normal and tangential velocity components are ramped up with either {\ct TAU\_V} or {\ct RAMP\_V}, as shown in Fig.~\ref{fig:tangential_velocity}.

\begin{figure}[ht!]
\begin{center}
\includegraphics[width=3.5in]{SCRIPT_FIGURES/tangential_velocity}
\caption[The {\ct tangential\_velocity} test case]{Normal and tangential velocity components at a louvered vent, compared to the ideal curve.}
\label{fig:tangential_velocity}
\end{center}
\end{figure}

In cases of limited mesh resolution, it may not be possible to describe a louvered vent or slot diffuser using {\ct VEL\_T} because there may not be enough mesh cells spanning the opening. In these cases, you might consider simply specifying a flat plate obstruction in front of the {\ct VENT} with an offset of one mesh cell. The plate will simply redirect the air flow in all lateral directions.

If the louvered vent is part of an HVAC system, see \ref{info:HVAClouvers} for details on how to specify the louver.


\subsection{Specified Normal Velocity Gradient}
\label{info:vel_grad}

It is sometimes desirable to specify a Neumann boundary condition (specified gradient) for the velocity in the direction normal to the boundary.  For example, the following allows inflow and outflow along the top of the domain, but $\partial w/\partial z = 0$.  Note that {\ct FREE\_SLIP=.TRUE.} only sets $\partial u/\partial z=0$ and $\partial v/\partial z=0$.
\begin{lstlisting}
&SURF ID = 'sky', COLOR = 'INVISIBLE', VEL_GRAD=0., FREE_SLIP=.TRUE. /
&VENT MB='ZMAX', SURF_ID='sky' /
\end{lstlisting}


\subsection{Species and Species Mass Flux Boundary Conditions}
\label{info:MASS_FLUX}

There are two types of species boundary conditions (see Chapter~\ref{info:SPEC} for a general discussion of gas species). By default, gas species do not penetrate solid surfaces and you need not specify anything if this is all you need. If the mass fraction of the species is to be some value at a forced flow boundary where {\ct VEL}, {\ct VOLUME\_FLOW}, or {\ct MASS\_FLUX\_TOTAL} is specified, set {\ct MASS\_FRACTION(:)} equal to the desired species mass fractions on the appropriate {\ct SURF} line. If the mass flux of the species is desired, set {\ct MASS\_FLUX(:)} instead of {\ct MASS\_FRACTION(:)}. If {\ct MASS\_FLUX(:)} is set, do not specify {\ct VEL}, {\ct VOLUME\_FLOW}, or \linebreak[4]{\ct MASS\_FLUX\_TOTAL}. These are automatically calculated based on the specified mass flux. The inputs {\ct MASS\_FLUX(:)} and typically {\ct MASS\_FRACTION(:)} should only be used for inflow boundary conditions.  {\ct MASS\_FLUX(:)} should be positive with units of \si{kg/(m$^2$.s)}. Also note that the background species cannot be specified when using {\ct MASS\_FRACTION}.  The mass fraction of the background species will be set to account for any mass fraction not specified with other species.

Here is an example of how to specify a surface that generates methane at a rate of 0.025~\si{kg/(m$^2$.s)}:
\begin{lstlisting}
&SPEC ID='METHANE' /
&SURF ID='METHANE BURNER', SPEC_ID(1)='METHANE', MASS_FLUX(1)=0.025 /
&VENT XB=..., SURF_ID='METHANE BURNER' /
\end{lstlisting}
Here is example of how to specify a surface that blows methane with a velocity of 0.1~m/s:
\begin{lstlisting}
&SPEC ID='METHANE' /
&SURF ID='METHANE BLOWER', MASS_FRACTION(1)=1.0, SPEC_ID(1)='METHANE', VEL=-0.1 /
&VENT XB=..., SURF_ID='METHANE BLOWER' /
\end{lstlisting}
Note that specifying a combination of {\ct VEL} and {\ct MASS\_FRACTION} can lead to inaccurate results if the specified velocity is small because diffusion will dominate the mass transport.  To obtain an accurate species mass flux at a boundary, use {\ct MASS\_FLUX}.

Alternatively, add {\ct CONVERT\_VOLUME\_TO\_MASS=.TRUE.} for velocity boundaries ({\ct VEL}, {\ct VOLUME\_FLOW}, or {\ct MASS\_FLUX\_TOTAL}), which converts volume flow to a mass flux based on the specified boundary composition ({\ct MASS\_FRACTION}) and temperature ({\ct TMP\_FRONT}):
\begin{equation}
\dot{m}_\alpha^{\prime\prime} = \rho Z_\alpha u = \frac{p_\infty \overline{W}}{R T} Z_\alpha \frac{\dot{Q}}{A}
\end{equation}
where $\rho$ is the density, $Z_\alpha$ is the mass fraction of $\alpha$, $u$ is the velocity normal to the surface, $p_\infty$ is the ambient pressure, $\overline{W}$ is the mixture molecular weight, $R$ is the ideal gas constant, $T$ is the surface temperature, $\dot{Q}$ is the volume flow rate, and $A$ is the area of the vent.  Note that using {\ct CONVERT\_VOLUME\_TO\_MASS=.TRUE.} converts the {\ct SURF} into a mass flux boundary condition and so velocity profiles may not be applied.

\subsection{Tangential Velocity Boundary Conditions at Solid Surfaces}
\label{info:WALL_MODEL}

The no-slip condition implies that the continuum tangential gas velocity at a surface is zero. In turbulent flow the velocity increases rapidly through a boundary layer that is only a few millimeters thick to its ``free-stream'' value. In most practical simulations, it is not possible to resolve this boundary layer directly; thus, an empirical model is used to represent its effect on the overall flow field. For a DNS (Direct Numerical Simulation), the velocity gradient at the wall is computed directly from the resolved velocity near the wall ({\ct NO\_SLIP=.TRUE.} by default). For an LES (Large Eddy Simulation), a ``log law'' wall model is applied. The ``sand grain'' surface roughness\footnote{Note the \emph{sand grain} roughness, $s$, is different than the \emph{aerodynamic} roughness, $z_0$, used in atmospheric flows (see Sec.~\ref{aerodynamic_roughness}).} (in meters) is set by {\ct ROUGHNESS} on {\ct SURF}. See the FDS Technical Reference Guide~\cite{FDS_Math_Guide} for wall model details. To force a solid boundary to have a free-slip condition, set {\ct FREE\_SLIP=.TRUE.}\footnote{This parameter sets the wall stress to zero (removes viscous friction).  It is \emph{not} equivalent to the {\ct SAWTOOTH=.FALSE.} functionality from versions of FDS prior to Version 6.} on the {\ct SURF} line. In LES, to override the wall model and force a no-slip boundary condition, set {\ct NO\_SLIP=.TRUE.} on the {\ct SURF} line.


\subsection{Synthetic Turbulence Inflow Boundary Conditions}
\label{info:synthetic_turbulence}

Real flows of low-viscosity fluids like air are rarely perfectly stationary in time or uniform in space---they are turbulent (to some degree). Of course, the turbulence characteristics of the flow may have a significant impact on mixing and other behaviors so the specification of nominally constant and uniform boundary conditions may be insufficient.  To address this issue, FDS employs a synthetic eddy method (SEM)\footnote{SEM only applies to velocity boundary conditions and so may not be used for HVAC vents, which are strict mass flux boundaries.}.  Refer to Jarrin \cite{Jarrin:2008} for a detailed description. In brief, ``eddies'' are injected into the flow at random positions on the boundary and advect with the mean flow over a short distance near the boundary equivalent to the maximum eddy length scale.  Once the eddy passes through this region it is recycled at the inlet of the boundary with a new random position and length scale. The eddies are idealized as velocity perturbations over a spherical region in space with a diameter (eddy length scale) selected from a uniform random distribution. The selection procedures guarantee that prescribed first and second-order statistics (including Reynolds stresses) are satisfied.

Synthetic turbulence is invoked by setting the number of eddies, {\ct N\_EDDY}, the characteristic eddy length scale, {\ct L\_EDDY}, and either the root mean square (RMS)
velocity fluctuation, {\ct VEL\_RMS}, or the Reynolds stress tensor components, {\ct REYNOLDS\_STRESS(3,3)} on the {\ct VENT} line.  In Fig.~\ref{fig:sem_profiles} we show examples using SEM for flat, parabolic, atmospheric, and ramp profiles with 10 \% turbulence intensity (see the {\ct sem\_*} test series in the Turbulence verification subdirectory).  The input lines for the atmospheric case are (see Section \ref{info:stratification} for further discussion of profile parameters).
\begin{lstlisting}
&SURF ID='inlet', VEL=-1, PROFILE='ATMOSPHERIC', Z0=0.5, PLE=0.3 /
&VENT MB='XMIN', SURF_ID='inlet', N_EDDY=100, L_EDDY=0.2, VEL_RMS=.1 /
\end{lstlisting}

\begin{figure}[ht]
\begin{tabular*}{\textwidth}{lr}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/sem_flat_leddy_p2} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/sem_par_leddy_p2} \\
\includegraphics[width=3.2in]{SCRIPT_FIGURES/sem_atm_leddy_p2} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/sem_ramp_leddy_p2}
\end{tabular*}
\caption[Synthetic Eddy Method vent profiles]{Synthetic Eddy Method vent profiles: flat (upper left), parabolic (upper right), atmospheric (lower left), and linear ramp (lower right).}
\label{fig:sem_profiles}
\end{figure}

Note that the Reynolds stress is symmetric and only the lower triangular part needs to be specified.  The RMS velocity fluctuation is isotropic (equivalent for each component). Thus, {\ct VEL\_RMS} $\equiv \sqrt{2k/3}$, where $k\equiv \langle\frac{1}{2}u_i^\prime u_i^\prime\rangle$ is the turbulent kinetic energy per unit mass. Below is an example illustrating the equivalence between the RMS velocity fluctuation and the diagonal components of the Reynolds stress. Note that if {\ct VEL\_RMS} is specified, this is equivalent to
\begin{lstlisting}
REYNOLDS_STRESS(1,1) = VEL_RMS**2
REYNOLDS_STRESS(2,2) = VEL_RMS**2
REYNOLDS_STRESS(3,3) = VEL_RMS**2
\end{lstlisting}
and all other components of {\ct REYNOLDS\_STRESS} are zero. If the fluctuations are not isotropic, then the Reynolds stresses must be specified componentwise.

In Chapter 7 of Jarrin's thesis~\cite{Jarrin:2008}, he introduces the Modified Synthetic Eddy Method in which the eddy length scales are anisotropic. This allows more realistic characterization of streamwise vortices in a turbulent boundary layer. To specify the length scales corresponding to the $\sigma_{ij}$ values in Jarrin's Eq.~(7.1) use {\ct L\_EDDY\_IJ(3,3)}.  Here is an example with random values for the eddy length scales and Reynolds stress components:

\begin{lstlisting}
&VENT XB=... , SURF_ID='WIND', N_EDDY=500,
   L_EDDY_IJ(1,1)=21.,  L_EDDY_IJ(1,2)=6.22, L_EDDY_IJ(1,3)=4.23
   L_EDDY_IJ(2,1)=2.35, L_EDDY_IJ(2,2)=5.66, L_EDDY_IJ(2,3)=2.50
   L_EDDY_IJ(3,1)=5.42, L_EDDY_IJ(3,2)=0.78, L_EDDY_IJ(3,3)=1.01
   REYNOLDS_STRESS(1,1)=2.16,  REYNOLDS_STRESS(1,2)=0.,   REYNOLDS_STRESS(1,3)=-0.47
   REYNOLDS_STRESS(2,1)=0.,    REYNOLDS_STRESS(2,2)=1.53, REYNOLDS_STRESS(2,3)=0.
   REYNOLDS_STRESS(3,1)=-0.47, REYNOLDS_STRESS(3,2)=0.,   REYNOLDS_STRESS(3,3)=4.259 /
\end{lstlisting}


\subsection{Random Mass Flux Variation}
\label{info:MASS_FLUX_VAR}

The current implementation of the Synthetic Eddy Method does not allow variation in mass flux defined on a {\ct SURF} line.  For example, {\ct HRRPUA} and {\ct MASS\_FLUX} boundary conditions are by default taken as constant for a given {\ct SURF}.  In reality, of course, this is rarely the case---generally there is some level of random variation in the mass flux on the surface.  In an attempt to accommodate this effect, we have implemented an experimental feature where the user may specify a mass flux variation as a fractional value with the parameter {\ct MASS\_FLUX\_VAR}.  For example, if you want a 10 \% variation in a heat release rate per unit area of 100 \si{kW/m^2} then use

\begin{lstlisting}
&SURF ID='burner', HRRPUA=100., MASS_FLUX_VAR=0.1 /
\end{lstlisting}

It may be helpful to use the boundary file output quantity {\ct MASS FLUX WALL CELL} to visualize the variation.  For example,

\begin{lstlisting}
&BNDF QUANTITY='MASS FLUX WALL CELL', CELL_CENTERED=.TRUE. /
\end{lstlisting}

\section{HVAC Systems: The \texorpdfstring{{\tt HVAC}}{HVAC} Namelist Group (Table \ref{tbl:HVAC})}
\label{info:HVAC}

There are occasions where simply defining fixed flow and fixed species boundary conditions is not sufficient to model the behavior of an HVAC (Heating, Ventilation, and Air Conditioning) system.
If the ability to transport heat and combustion products through a duct network or the ability to fully account for the pressurization of a compartment due to a fire on the flows in a duct network is important, you can make use of a coupled HVAC network solver. The solver computes the flows through a duct network described as a mapping of duct segments and nodes where a node is either the joining of two or more ducts (a tee for example) or where a duct segment connects to the FDS computational domain. For more information on coupled hybrid modelling in fire safety engineering, interested readers may want to refer to Ralph et al.'s literature review of the topic~\cite{Ralph:1}.

By default the HVAC solver does not allow for mass storage in the duct network (i.e., what goes in during a time step, goes out during a time step). However, if you set {\ct HVAC\_MASS\_TRANSPORT=.TRUE.} on the {\ct MISC} line, then the HVAC solver will account for mass storage and will compute transient species and energy transport through the ducts.

HVAC components such as fans and binary dampers (fully open or fully closed) can be included in the HVAC network and are coupled to the FDS control function capability.  You can select from three fan models.

The HVAC solver is invoked if there is an {\ct HVAC} namelist group present in the input file.
An HVAC network is defined by providing inputs for the ducts; duct nodes; and any fans, dampers, filters, or heating and coiling coils present in the system.
Additionally you must define the locations where the HVAC network joins the computational domain.  The basic syntax for an {\ct HVAC} component is:

\begin{lstlisting}
&HVAC TYPE_ID='componenttype', ID='componentname', ... /
\end{lstlisting}


\begin{description}
\item[{\ct TYPE\_ID}] is a character string that indicates the type of component that the namelist group is defining.   {\ct TYPE\_ID} can be {\ct DUCT}, {\ct NODE}, {\ct FAN}, {\ct FILTER}, {\ct AIRCOIL}, or {\ct LEAK} (see ~Section~\ref{info:local_leakage}).
\item[{\ct ID}] is a character string giving a name to the component.  The name must be unique amongst all other components of that type; however, the same name can be given to components of different types (i.e., a duct and a node can have the same name but two ducts cannot).
\end{description}
A number of examples of simple HVAC systems are given in the HVAC folder of the sample cases and are discussed in the FDS Verification Guide.

As described in the Technical Reference Manual, the HVAC pressure solution is not directly coupled to the FDS pressure solution. Rather there is implicit coupling using the wall boundary condition for HVAC vents. At times this can result in stability problems. There are two methods of attempting to resolve this.

The first method is the keyword {\ct HVAC\_PRES\_RELAX} on the {\ct MISC} line with a default value of 0.5. At each time step FDS evaluates the average pressure in the FDS gas cells adjacent to nodes connecting the FDS domain to the HVAC network. The node pressure at time step n+1 is taken as:
\be
P_{node}^{n+1}=P_{FDS} \; (1-{\mathtt{HVAC\_PRES\_RELAX}}) \; + \; P_{node}^n \; {\mathtt{HVAC\_PRES\_RELAX}}
\ee
Setting this parameter closer to 1 reduces the sensitivity of the HVAC solution to short, transient pressure changes in the FDS domain; however, doing so will also result in the HVAC solution lagging for longer duration pressure changes.

The second method is setting the keyword {\ct HVAC\_LOCAL\_PRESSURE} on the {\ct MISC} line. When set, this will cause FDS to use the {\ct ZONE} pressure at a vent plus the stagnation pressure of any flow normal to the vent to determine the pressure boundary condition for a node connected to the FDS domain rather than the {\ct ZONE} pressure plus the the pressure derived from the local value of $\cH$. Note this means a sealed room must have a {\ct ZONE} assigned to it.

\subsection{HVAC Duct Parameters}
\label{info:HVACduct}

A typical input line specifying a duct is as follows:
\begin{lstlisting}
&HVAC TYPE_ID='DUCT', ID='ductname', NODE_ID='node 1','node 2', AREA=3.14,
      LOSS=1.,1., LENGTH=2., ROUGHNESS=0.001, FAN_ID='fan 1', DEVC_ID='device 1' /
\end{lstlisting}
Or, if you are using {\ct HVAC\_MASS\_TRANSPORT=.TRUE.}, as follows:
\begin{lstlisting}
&HVAC TYPE_ID='DUCT', ID='ductname', NODE_ID='node 1','node 2', AREA=3.14,
      LOSS=1.,1., LENGTH=2., ROUGHNESS=0.001, FAN_ID='fan 1', DEVC_ID='device 1',
      DUCT_INTERP_TYPE='NODE1', N_CELLS=200 /
\end{lstlisting}
where:
\begin{description}
\item[{\ct AIRCOIL\_ID}] is the {\ct ID} of an aircoil located in the duct.  The operation of the aircoil can be controlled by either a device or a control function.
\item[{\ct AREA}] is the cross sectional area of the duct in m$^2$.
\item[{\ct DAMPER}] is a logical parameter indicating the presence of a damper in the duct. The state of the damper is controlled by either a device or a control function (see Section~\ref{info:HVACdamper}).
\item[{\ct DIAMETER}] is the diameter of the duct in m.  If only {\ct DIAMETER} is specified, the {\ct AREA} will be computed assuming a round duct.  Do not specify both {\ct DIAMETER} and {\ct PERIMETER}.
\item[{\ct DEVC\_ID}]  is the {\ct ID} of a {\ct DEVC} for a damper, fan, or aircoil in the duct. An alternative is {\ct CTRL\_ID}.
\item[{\ct DUCT\_INTERP\_TYPE}] Used when {\ct HVAC\_MASS\_TRANSPORT=.TRUE.}. It determines whether the duct is initialized with data from the first node ({\ct NODE1}) or the second node ({\ct NODE2}). Continuous runs of ducts cannot have a mix of interpolation methods (refer to Section~\ref{info:hvacmasstransport}).
\item[{\ct FAN\_ID}] is the {\ct ID} of a fan located in the duct. Instead of specifying a {\ct FAN\_ID}, you could specify the {\ct VOLUME\_FLOW} rate (m$^3$/s) through the duct. The operation of the fan can be controlled by either a device or a control function.
\item[{\ct LENGTH}] is the {\ct LENGTH} of the duct in m.  Note that {\ct LENGTH} is not computed automatically as the difference between the {\ct XYZ} of the duct's endpoints.
\item[{\ct LOSS}] is a pair of real numbers giving the forward and reverse dimensionless "minor losses" loss coefficient (\(K_{\mbox{\tiny minor}}\)) in the duct. Minor losses are pressure losses through components such as tees, valves and bends. However, you can use {\ct LOSS} to represent wall friction losses if you want - in this case ensure you leave {\ct ROUGHNESS} unset so that the HVAC solver does not compute a friction factor. The forward direction is defined as flow from the first node listed in {\ct NODE\_ID} to the second node listed in {\ct NODE\_ID}.
\item[{\ct MASS\_FLOW}] is a fixed mass flow rate (kg/s) through the duct.  Only specify one of {\ct MASS\_FLOW} or {\ct VOLUME\_FLOW}.  You can change its value in time either using the characteristic time, {\ct TAU\_VF},  to define a tanh ({\ct TAU\_VF}>0) or t$^2$ ramp ({\ct TAU\_VF}<0); or you can specify a {\ct RAMP\_ID}.  {\ct MASS\_FLOW} should only be specified for conditions where the upstream node density will not change during the solution process.
\item[{\ct N\_CELLS}] Used when {\ct HVAC\_MASS\_TRANSPORT=.TRUE.}. It defines the number of cells used in a discretized duct.
\item[{\ct NODE\_ID}] gives the {\ct ID}s of the nodes on either end of the duct segment.  Positive velocity in a duct is defined as flow from the first node to second node.
\item[{\ct PERIMETER}] is used along with {\ct AREA} to specify a duct with non-circular cross-section.  The {\ct DIAMETER} will be computed as the hydraulic diameter.
\item[{\ct RAMP\_LOSS}] If specified this {\ct RAMP} is a multiplier for the {\ct LOSS}.
\item[{\ct REVERSE}]  is a logical parameter that when {\ct .TRUE.} indicates that the specified {\ct FAN\_ID} blows from the second node to the first. {\ct REVERSE} has no effect on {\ct VOLUME\_FLOW} or {\ct MASS\_FLOW} as a duct input. If {\ct VOLUME\_FLOW} or {\ct MASS\_FLOW} is specified for a duct and the reverse flow direction is needed, change the sign of the input to negative.
\item[{\ct ROUGHNESS}] is the absolute roughness in m of the duct that is used to compute the friction factor for the duct. If {\ct ROUGHNESS} is not set, the HVAC solver will not compute the friction factor and the wall friction will be zero - if this is the case you may want to account for wall friction losses in {\ct LOSS}. "Perfectly smooth" ducts and pipes still have wall losses and therefore setting {\ct ROUGHNESS} to zero will tell the HVAC solver to compute the minimum friction factor (which is non-zero) - this is not the same as leaving {\ct ROUGHNESS} unset.
\item[{\ct VOLUME\_FLOW}] is a fixed flow rate (m$^3$/s) through the duct.  Only specify one of {\ct MASS\_FLOW} or {\ct VOLUME\_FLOW}. If you specify {\ct VOLUME\_FLOW}, you can change its value in time either using the characteristic time, {\ct TAU\_VF},  to define a tanh ({\ct TAU\_VF}>0) or t$^2$ ramp ({\ct TAU\_VF}<0); or you can specify a {\ct RAMP\_ID}.  This cannot be controlled by a device or control function; however, a constant volume flow {\ct FAN} can be.
\end{description}
Note that only one of {\ct AIRCOIL\_ID}, {\ct DAMPER}, or {\ct FAN\_ID} should be specified for a duct.  Also note that if one of these is specified, but no device or control function is provided, then the item will be assumed to be on or open as appropriate.

To reduce the computational cost of the HVAC solver, a duct should be considered as any length of duct that connects two items that must be defined as nodes (i.e., a connection to the FDS domain, a filter, or a location where more than two ducts join).  That is, a duct should be considered as any portion of the HVAC system where flow can only be in one direction at given point in time (flow can reverse direction over time).  For example the top of Figure~\ref{fig:HVAC_Simplify} shows a segment of an HVAC system where flow from a tee goes through an expansion fitting, two elbows, an expansion fitting, and a straight length of duct before it terminates as a connection to the FDS domain.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=3in]{FIGURES/hvac-simplify}
\end{center}
\caption[An example of simplifying a complex duct]{An example of simplifying a complex duct.}
\label{fig:HVAC_Simplify}
\end{figure}

This could be input as each individual fitting or duct with its associated area and loss as shown in the middle of the figure; however, this would result in five duct segments (one for each component) with six node connections resulting in eleven parameters (five velocities and six pressures) which must be solved for.  This is not needed since whatever the flow rate is in any one segment of the duct, that same flow rate exists in all other segments; thus, the velocities in any segment can be found by taking the area ratios, $v_1/v_2=A_2/A_1$.  Since flow losses are proportional to the square of the velocity, an equivalent duct can be constructed using the total length of the duct, and a representative area ($A_{\mbox{\tiny eff}}$) or diameter.  The pressure losses associated with all the segments of the duct can be collapsed to a single effective loss ($K_{\mbox{\tiny eff}}$) by summing all of the fitting losses ($K_{\mbox{\tiny minor}}$) through the duct as follows:
\be K_{\mbox{\tiny eff}} = \sum_i {(K_{\mbox{\tiny minor}})_i \frac {A_{\mbox{\tiny eff}}}{A_i}} \ee
where $i$ is a fitting and $A_i$ is the area associated with the fitting loss.

\subsection{HVAC Dampers}
\label{info:HVACdamper}

Dampers can be modeled in one of two ways.

The first method is a simple binary (flow or no flow) damper. This can be placed in a duct by adding the keyword {\ct DAMPER} along with either a {\ct CTRL\_ID} or {\ct DEVC\_ID}.  When the control or device is {\ct .TRUE.} the damper will be open, and when {\ct .FALSE.} the damper will be closed and block 100~\% of the duct area.  The example below shows a duct with a damper that that is linked to a {\ct DEVC} that closes the damper at 10~s.

\begin{lstlisting}
&HVAC TYPE_ID='DUCT',ID='EXHAUST 2',NODE_ID='TEE','EXHAUST 2',AREA=0.01,
      LENGTH=1.0,LOSS=0,0,DAMPER=.TRUE.,DEVC_ID='TIMER'/
&DEVC QUANTITY='TIME',ID='TIMER',SETPOINT=10,INITIAL_STATE=.TRUE.,XYZ=0,0,0/
\end{lstlisting}

If you want the damper to start in the closed position and then open at a later time, the {\ct INITIAL\_STATE} of the {\ct DEVC} should not be set to {\ct .TRUE.}. The following example shows a duct with a damper which starts closed and then opens at 10~s. For further details see the {\ct HVAC\_damper} example case, which is documented in the Verification Guide.

\begin{lstlisting}
&HVAC TYPE_ID='DUCT',ID='EXHAUST 2',NODE_ID='TEE','EXHAUST 2',AREA=0.01,
      LENGTH=1.0,LOSS=0,0,DAMPER=.TRUE.,DEVC_ID='TIMER'/
&DEVC QUANTITY='TIME',ID='TIMER',SETPOINT=10,XYZ=0,0,0/
\end{lstlisting}

The second method is to specify a {\ct RAMP\_LOSS} for the duct. This approach multiplies the {\ct LOSS} array for the duct by the output of the {\ct RAMP}. This allows for dampers that have leakage and/or dampers that have a variable position other than fully open or fully closed. An example is shown below where the {\ct LOSS} in the duct changes from 1,1 at 10~s to 2000,2000 at 11~s.

\begin{lstlisting}
&HVAC TYPE_ID='DUCT',ID='EXHAUST 2',NODE_ID='TEE','EXHAUST 2',AREA=0.01,
      LENGTH=1.0,LOSS=1,1,RAMP_LOSS='LOSS RAMP'/
&RAMP ID='LOSS RAMP',T=10,F=1/
&RAMP ID='LOSS RAMP',T=11,F=2000/
\end{lstlisting}


\subsection{HVAC Node Parameters}
\label{info:HVACnode}

Below are three example duct node inputs representing a typical tee-type connection (multiple ducts being joined), a connection to the FDS domain, and a connection to the ambient outside the FDS domain.

\begin{lstlisting}
&HVAC TYPE_ID='NODE', ID='tee', DUCT_ID='duct 1','duct 2',..'duct n',
      LOSS=lossarray, XYZ=x,y,z /
&HVAC TYPE_ID='NODE', ID='FDS connection', DUCT_ID='duct 1', VENT_ID='vent',
      LOSS=enter,exit /
&HVAC TYPE_ID='NODE', ID='ambient', DUCT_ID='duct 1', LOSS=enter,exit,
      XYZ=x,y,z, AMBIENT=.TRUE. /
\end{lstlisting}

\noindent where:

\begin{description}
\item[{\ct AMBIENT}] is a logical value.  If {\ct .TRUE.}, then the node is connected to the ambient (i.e., it is equivalent to the {\ct OPEN} boundary condition on a {\ct SURF} line).
\item[{\ct DUCT\_ID}] gives the {\ct ID}s of the ducts connected to the node.  Up to 10 ducts can be connected to a node.
\item[{\ct FILTER\_ID}] gives the {\ct ID} a filter located at the node.  A node with a filter can only have two connected ducts.
\item[{\ct LOSS}] is an $n$ by $n$ array of real numbers giving the dimensionless loss coefficients for the node.  {\ct LOSS(I,J)} is the loss coefficient for flow from duct {\ct I} to duct {\ct J} expressed in terms of the downstream duct area (see discussion in ~\ref{info:HVACduct} on how to adjust losses for area changes).  For a terminal node (e.g., a node connected to the ambient or to a {\ct VENT}) the {\ct LOSS} is entered as a pair of numbers representing loss coefficient for flow entering the HVAC system and for flow exiting the HVAC system.
\item[{\ct VENT\_ID}] is the name of the {\ct VENT} where the node connects to the FDS computational domain.  No two {\ct VENTs} should be defined with the same {\ct VENT\_ID}.
\item[{\ct XYZ}] is a triplet of real numbers giving the coordinates of the node.  This location is used to compute buoyancy heads.
If the node is connected to the FDS domain, then do not specify {\ct XYZ}.  FDS will compute it as the centroid of the {\ct VENT}. Note that if you do not specify an {\ct XYZ} for an interior node, then FDS will use the default value of 0,0,0.
\end{description}

\noindent
A duct node must either have two or more ducts attached to it or it must have either {\ct AMBIENT=.TRUE.} or a specified {\ct VENT\_ID}.  When defining a {\ct VENT} as a component of an HVAC system you must set {\ct SURF\_ID} to {\ct 'HVAC'} and you must set the {\ct VENT\_ID}.

It is permissible to have individual {\ct VENT} lines for an HVAC system span multiple meshes.

\subsection{HVAC Fan Parameters}
\label{info:HVACfan}

Below are sample inputs for the three types of fans supported by FDS.

\begin{lstlisting}
&HVAC TYPE_ID='FAN', ID='constant volume', VOLUME_FLOW=1.0, LOSS=2./
&HVAC TYPE_ID='FAN', ID='quadratic', MAX_FLOW=1., MAX_PRESSURE=1000., LOSS=2. /
&HVAC TYPE_ID='FAN', ID='user fan curve', RAMP_ID='fan curve',  LOSS=2. /
\end{lstlisting}

\noindent where:

\begin{description}
\item[{\ct LOSS}] is the loss coefficient for flow through the fan when it is not operational.
\item[{\ct MAX\_FLOW}] is the maximum volumetric flow of the fan in m$^3$/s.  This input activates a quadratic fan model.
\item[{\ct MAX\_PRESSURE}] is the stall pressure of the fan in units of Pa.  This input activates a quadratic fan model.
\item[{\ct RAMP\_ID}] identifies the {\ct RAMP} that contains a table of pressure drop across the fan (Pa) versus the volumetric flow rates (m$^3$/s) for a user-defined fan curve.
\item[{\ct TAU\_FAN}] defines a tanh ({\ct TAU\_FAN} > 0) or t$^2$ ramp ({\ct TAU\_FAN} < 0) for the fan.  This is applied to the flow rate computed by any of the three types (constant flow, quadratic, or user-defined ramp) of fans.
\item[{\ct VOLUME\_FLOW}] is the fixed volumetric flow of the fan (m$^3$/s).  If you wish to have a time dependent flow use the {\ct VOLUME\_FLOW} input for a duct rather than for a fan.
\end{description}

\noindent
Note that only one set of fan model inputs ({\ct VOLUME\_FLOW}, {\ct RAMP\_ID}, or {\ct MAX\_FLOW + MAX\_PRESSURE}) should be specified.
Also note that {\ct FAN} defines a class of fans rather than one specific fan. Therefore, more than one duct can reference a single {\ct FAN}.

\subsubsection{Fan Curves}
\label{info:Fan_Curves}

In Section~\ref{info:Velocity_BC} there is a discussion of velocity boundary conditions,
in which a fan is modeled simply as a solid boundary that blows or
sucks air, regardless of the surrounding pressure field. In the HVAC model, this approach to modeling a fan occurs when the fan is specified with a {\ct VOLUME\_FLOW}.
In reality, fans operate based on
the pressure drop across the duct or manifold in which they are
installed. A very simple ``fan curve'' is given by:
\be \dot{V}_{\hbox{\footnotesize fan}} = \dot{V}_{\hbox{\footnotesize max}} \;
   \hbox{sign} (\Delta p_{\hbox{\footnotesize max}}-\Delta p)
   \sqrt{ \frac{ |\Delta p - \Delta p_{\hbox{\footnotesize max}}|}{\Delta p_{\hbox{\footnotesize max}} } }  \label{fan_curve} \ee
This simple ``fan curve'' is the ``quadratic'' fan model as the pressure is proportional to the square of the volume flow rate.

The volume flow in the absence of a pressure difference, {\ct MAX\_FLOW}, is given by $\dot{V}_{\hbox{\footnotesize max}}$.  The pressure difference, $\Delta p=p_1-p_2$, indicates the difference in
pressure between the downstream compartment, or ``zone,'' and the upstream. The subscript 1 indicates downstream and 2 indicates upstream.
The term, $\Delta p_{\hbox{\footnotesize max}}$, is the maximum
pressure difference, {\ct MAX\_PRESSURE}, the fan can operate upon, and it is assumed to be a positive number.
The flow through a fan will decrease from $\dot{V}_{\hbox{\footnotesize max}}$ at zero pressure difference to 0~m$^3$/s at $\Delta p_{\hbox{\footnotesize max}}$.
If the pressure difference increases beyond this, air will be forced backwards through the fan.   If the downstream pressure becomes negative, then the volume flow through the fan will increase beyond {\ct MAX\_FLOW}. More complicated fan curves can be specified by defining a {\ct RAMP}.  In the example inputs below, one fan of each type is specified.  A constant volume flow fan with a {\ct VOLUME\_FLOW} of 10~m$^3$/s, a quadratic fan with {\ct MAX\_FLUX=10} and {\ct MAX\_PRESSURE=500}, and a user-defined fan with the {\ct RAMP} set to the values of the quadratic fan in 200~Pa increments,

\begin{lstlisting}
&HVAC TYPE_ID='FAN', ID='constant volume', VOLUME_FLOW=10.0/
&HVAC TYPE_ID='FAN', ID='quadratic', MAX_FLOW=10., MAX_PRESSURE=500./
&HVAC TYPE_ID='FAN', ID='user fan curve', RAMP_ID='fan curve'/

&RAMP ID='fan curve',T=-10.00,F= 1000/
&RAMP ID='fan curve',T= -7.75,F=  800/
&RAMP ID='fan curve',T= -4.47,F=  600/
&RAMP ID='fan curve',T=  4.47,F=  400/
&RAMP ID='fan curve',T=  7.75,F=  200/
&RAMP ID='fan curve',T= 10.00,F=    0/
&RAMP ID='fan curve',T= 11.83,F= -200/
&RAMP ID='fan curve',T= 13.42,F= -400/
&RAMP ID='fan curve',T= 14.83,F= -600/
&RAMP ID='fan curve',T= 16.12,F= -800/
&RAMP ID='fan curve',T= 17.32,F=-1000/
\end{lstlisting}

Figure~\ref{fig:Fan_Curve} displays the fan curves for the inputs shown above.  Additional examples can be found in the {\ct ashrae7} and {\ct fan\_test} example cases, which are documented in the Verification Guide.

\begin{figure}[ht!]
\begin{center}
\includegraphics[width=3.5in]{SCRIPT_FIGURES/fan_curve}
\caption[Example of fan curves]{Fan curves corresponding to a constant fan with {\ct VOLUME\_FLOW=10}, a quadratic fan with {\ct MAX\_FLOW=10} and {\ct MAX\_PRESSURE=500}, and a user-defined {\ct RAMP} equivalent to the quadratic fan.}
\label{fig:Fan_Curve}
\end{center}
\end{figure}

\subsubsection{Jet Fans}

Fans do not have to be mounted on a solid wall, like a supply or an exhaust fan.
If you just want to blow gases in a particular direction, create an
obstruction {\ct OBST}, at least one cell thick, and apply to it {\ct VENT} lines that are
associated with a simple HVAC system.
This allows hot, smokey gases to pass through the
obstruction, much like a free-standing fan.  See the example case {\ct jet\_fan.fds} which places a louvered fan (blowing diagonally down) near a fire (see Fig.~\ref{fig:Jet_Fan}).

You may also want to construct a {\em shroud} around the fan using four flat plates arranged to form
a short passageway that draws gases in one side and expels them out the other. The obstruction representing the fan can be positioned about halfway along the passage (if a louvered fan is being used, place the fan at the end of the passage).

\begin{figure}[ht!]
\begin{center}
\includegraphics[width=4.5in]{SCRIPT_FIGURES/jet_fan}
\caption[Example of a jet fan]{Jet fan with a louvered output {\ct UVW=-1,0,-1}.}
\label{fig:Jet_Fan}
\end{center}
\end{figure}


\subsection{HVAC Filter Parameters}
\label{info:HVACfilter}

A sample input for a filter is given by:
\begin{lstlisting}
&HVAC TYPE_ID='FILTER', ID='filter 1', LOADING=0., SPEC_ID='SOOT',
      EFFICIENCY=0.99, LOADING_MULTIPLIER=1, CLEAN_LOSS=2., LOSS=100./
\end{lstlisting}
where:
\begin{description}
\item[{\ct CLEAN\_LOSS}] is the dimensionless loss coefficient for flow through the filter when it is clean (zero loading).
\item[{\ct EFFICIENCY}] is an array of the species removal efficiency from 0 to 1 where 0 is no removal of that species and 1 is complete filtration of the species.  The species are identified using {\ct SPEC\_ID}.
\item[{\ct LOADING}] is an array of the initial loading (kg) of the filter for each species being filtered.
\item[{\ct LOADING\_MULTIPLIER}] is an array of the species multiplier, $M_i$, used in computing the total filter loading when computing the loss coefficient of the filter.
\item[{\ct LOSS}] invokes a linear loss coefficient model where the dimensionless loss coefficient, $K$, is given as a linear function of the total loading, $K_{\si{FILTER}}=K_{\si{CLEAN\_LOSS}}+K_{\si{LOSS}} \sum \left( L_i M_i \right)$, where $L_i$ is the species loading and $M_i$ is a multiplier.  Only one of {\ct LOSS} or {\ct RAMP\_ID} should be specified.
\item[{\ct RAMP\_ID}] identifies the {\ct RAMP} that contains a table of pressure drop across the filter as a function of total loading (the summation term given in the definition of {\ct LOSS} above).   Only one of {\ct LOSS} or {\ct RAMP\_ID} should be specified.
\item[{\ct SPEC\_ID}] identifies the tracked species for the inputs of {\ct LOADING\_MULTIPLIER} and {\ct LOADING}.
\end{description}
A sample set of filter inputs is shown below.  These lines define a filter that removes the species {\ct PARTICULATE} with 100~\% efficiency.  The filter has an initial loss coefficient of 1 and that loss increases by a factor of 7332 for each kg of {\ct PARTICULATE} captured by the filter.  For further details see the sample case {\ct HVAC\_filter}, which is documented in the Verification Guide.

\begin{lstlisting}
&SPEC ID='PARTICULATE',MW=28.,MASS_FRACTION_0=0.001,SPECIFIC_HEAT=1./
&HVAC TYPE_ID='NODE',ID='FILTER',DUCT_ID='DUCT1','DUCT2',XYZ(3)=0.55,
      FILTER_ID='FILTER'/
&HVAC TYPE_ID='FILTER',ID='FILTER',CLEAN_LOSS=1.,SPEC_ID='PARTICULATE',EFFICIENCY=1.,
      LOSS=7732.446,LOADING_MULTIPLIER=1./
\end{lstlisting}

Note that a filter input refers to a class of filters and that multiple ducts can reference the same filter definition.

\subsection{HVAC Aircoil Parameters}
\label{info:HVACaircoil}
\label{HVAC_aircoil}

An aircoil refers to a device that either adds or removes heat from air flowing through a duct.  In a typical HVAC system this is done by blowing the air over a heat exchanger (hence the term aircoil) containing a working fluid such as chilled water or a refrigerant.  A sample input line is as follows:
\begin{lstlisting}
&HVAC TYPE_ID='AIRCOIL', ID='aircoil 1', EFFICIENCY=0.5,
      COOLANT_SPECIFIC_HEAT=4.186, COOLANT_TEMPERATURE=10., COOLANT_MASS_FLOW=1./
\end{lstlisting}
where:
\begin{description}
\item[{\ct COOLANT\_MASS\_FLOW}] is the flow rate of the working fluid (kg/s).
\item[{\ct COOLANT\_SPECIFIC\_HEAT}] is the specific heat (\si{kJ/(kg.K)}) of the working fluid.
\item[{\ct COOLANT\_TEMPERATURE}] is the inlet temperature of the working fluid ($^\circ$C).
\item[{\ct EFFICIENCY}] is the heat exchanger efficiency, $\eta$, from 0 to 1.  A value of 1 indicates the exit temperatures on both sides of the heat exchanger will be equal.
\item[{\ct FIXED\_Q}] is the constant heat exchange rate. A negative value indicates heat removal from the duct.  The heat exchange rate can be controlled by either {\ct RAMP\_ID} or by {\ct TAU\_AC}.
\item[{\ct TAU\_AC}]  defines a tanh ({\ct TAU\_AC}>0) or t$^2$ ramp ({\ct TAU\_AC}<0) for the aircoil.  This is applied to the {\ct FIXED\_Q} of the aircoil. Alternatively, a {\ct RAMP\_ID} can be given.
\end{description}
Note that either {\ct FIXED\_Q} or the set {\ct COOLANT\_SPECIFIC\_HEAT}, {\ct COOLANT\_MASS\_FLOW}, \linebreak[4]{\ct COOLANT\_TEMPERATURE}, and {\ct EFFICIENCY} should be specified.  In the latter case, the heat exchange is computed as a two step process.  First, the outlet temperature is determined assuming 100 \% efficient (i.e., both fluids exit at the same temperature):
\be
  T_{\rm fluid,out}=\frac{c_{p,{\rm gas}} \, u_{\rm duct} \, A_{\rm duct} \, \rho_{\rm duct} \, T_{\rm duct,in} + c_{p,{\rm fluid}} \, \dm_{\rm fluid} \, T_{\rm fluid,in}}{c_{p,{\rm gas}} \, u_{\rm duct} \, A_{\rm duct} \, \rho_{\rm duct} + c_{p,{\rm fluid}} \, \dm_{\rm fluid}}
\ee
Second, the actual heat exchanged is computed using the {\ct EFFICIENCY}.
\be
  \dq_{\rm coil}=\eta \, c_{p,{\rm fluid}} \, \dm_{\rm fluid} \left( T_{\rm fluid,in} - T_{\rm fluid,out} \right)
\ee
Note that an aircoil input refers to a class of aircoils and that multiple ducts can reference the same aircoil definition.

The sample input file {\ct HVAC\_aircoil.fds} demonstrates the use of the aircoil inputs.  A constant flow duct removes air (defined as 28~g/mol with a specific heat of 1~\si{kJ/(kg.K)}) from the floor and injects in through the ceiling at a volume flow rate of 1~\si{m^3/s}.  An aircoil is defined with a working fluid flowing at 10~kg/s and 100~$^\circ$C with a specific heat of 4~\si{kJ/(kg.K)}.  The aircoil has an efficiency of 50~\%.  Using the above equations the aircoil will add 45.2~kW of heat to the gas flowing through the duct resulting in a duct exit temperature of 332~K. These results are shown in  Fig.~\ref{fig_aircoil}.

\begin{figure}[t]
   \begin{tabular*}{\textwidth}{l@{\extracolsep{\fill}}r}
      \scalebox{1}{ \includegraphics[width=3.2in]{SCRIPT_FIGURES/HVAC_aircoil_Q} } &
      \scalebox{1}{ \includegraphics[width=3.2in]{SCRIPT_FIGURES/HVAC_aircoil_T} }
   \end{tabular*}
   \caption[Results of the {\ct HVAC\_aircoil} case]{(Left) Heat addition and (Right) duct exit temperature for the {\ct HVAC\_aircoil} case.}
   \label{fig_aircoil}
\end{figure}

\subsection{Louvered HVAC Vents}
\label{info:HVAClouvers}

The HVAC system being modeled may either have louvers that redirect the flow leaving a vent or the orientation of the real vent may not lie along one of the axes in FDS.  To define the flow direction for an HVAC outlet, you can use the keyword {\ct UVW} on {\ct VENT}.  {\ct UVW} is the vector indicating the direction of flow from the {\ct VENT}.  For example:
\begin{lstlisting}
&OBST XB=1.0,2.0,0.0,1.0,0.0,1.0 /
&VENT XB=1.0,1.0,0.0,1.0,0.0,1.0, SURF_ID='HVAC', ID='HVAC OUTLET', UVW=-1,0,1 /
\end{lstlisting}
The above input defines a vent lying in the $y$-$z$ plane facing in the $-x$ direction.  The flow vector indicates that the flow from this vent is in the $-x$ direction with a 45 degree up angle (the $x$ and $z$ components are equal in size).  FDS will set the tangential velocity of the vent to obtain the specified direction indicated by {\ct UVW}.  This will only be done if the vent is inputting gas into the domain. Note that the values given for {\ct UVW} are normalized to a unit vector.

\subsection{HVAC Mass Transport}
\label{info:hvacmasstransport}

If you set {\ct HVAC\_MASS\_TRANSPORT=.TRUE.} on the {\ct MISC} line this will call the HVAC mass transport subroutine. This subroutine accounts for mass storage in the duct network and transport time of species and energy. The current HVAC solver does not account for heat loss in the HVAC network.

To avoid the possibility of there being no available initialization data for a duct run (a series of ducts connected to one another via ducts and nodes), {\ct DUCT\_INTERP\_TYPE} in each comprising duct must be consistent. This ensures that there is a non-internal duct node from which the duct run adopts its initial data. If duct interpolation is set to {\ct NODE1} then data from the first node of the lowest numbered duct in the duct run is initialized in the duct, if it is set to {\ct NODE2} then data from the second node of the highest numbered duct in the duct run is initialized in the duct. {\ct DUCT\_INTERP\_TYPE} is related to initialization only; if the FDS domain is initialized as ambient/background data then there will be no difference in output when using either duct interpolation method.

You can increase or decrease the number of cells each discretized duct has, to increase solution accuracy or decrease simulation time respectively. The default value is set based upon a cell size of \SI{100}{\milli\meter}. Where the duct is not divisible by \SI{100}{\milli\meter}, the number of cells is rounded up to the nearest integer (e.g. a duct with a length of \SI{1.05}{\meter} will have \num{11} cells). Ducts with a length of less than \SI{100}{\milli\meter} adopt a cell number of 2. If {\ct N\_CELLS=1} is assigned to a duct then, even if {\ct HVAC\_MASS\_TRANSPORT=.TRUE.}, the HVAC mass transport subroutine will not be called for this duct.

If you are using {\ct DEVC}s to output spatially-integrated statistics as per Section~\ref{info:statistics} (such as {\ct VOLUME MEAN}, {\ct VOLUME INTEGRAL} or {\ct MASS INTEGRAL}) then be aware that, even if the integration volume bound by {\ct XB} encapsulates the spatial location of a duct, the quantity in the duct will not be recorded by the {\ct DEVC}. For example, if there is \SI{1}{\meter\cubed} of species~\num{1} initialized in an upstream FDS compartment which is transported to a downstream FDS compartment via an HVAC network with a total volume greater than \SI{1}{\meter\cubed}, the value of total mass of species~\num{1} output by a {\ct DEVC} recording the {\ct VOLUME INTEGRAL} of {\ct DENSITY} will reduce to zero during the time for which it is in the HVAC network domain.

\section{Pressure-Related Effects: The \texorpdfstring{{\tt ZONE}}{ZONE} Namelist Group (Table \ref{tbl:VENT})}
\label{info:ZONE}

FDS assumes pressure to be composed of a ``background'' component, $\bp(z,t)$, plus a perturbation pressure, $\tp(\bx,t)$. Most often, $\bp$ is just the hydrostatic pressure, and $\tp$ is the flow-induced spatially-resolved perturbation. You can specify any number of sealed compartments within the computational domain that can have their own ``background'' pressures, and these compartments, or ``pressure zones,'' can be connected via leakage and duct paths whose flow rates are tied to the pressure of the adjacent zones.



\subsection{Specifying Pressure Zones}
\label{info:ZONE_Basics}

A pressure zone can be any region within the computational domain that is separated from the rest of the domain, or the exterior, by solid obstructions. There is currently no algorithm within FDS to identify these zones based solely on your specified obstructions. Consequently, it is necessary that you identify these zones explicitly in the input file. The basic syntax for a pressure {\ct ZONE} is:
\begin{lstlisting}
&ZONE XB=0.3,1.2,0.4,2.9,0.3,4.5 /
\end{lstlisting}
This means that the rectangular region, $0.3<x<1.2$, $0.4<y<2.9$, $0.3<z<4.5$, is assumed to be within a sealed compartment. There can be multiple {\ct ZONE}s declared. The indices of the zones, which are required for the specification of leaks and fans, are determined simply by the order in which they are specified in the input file. By default, the exterior of the computational domain is Zone~0. If there are no {\ct OPEN} boundaries, the entire computational domain will be assumed to be Zone~1.

There are several restrictions to assigning pressure zones. First, the declared pressure zones must be completely within a region of the domain that is bordered by solid obstructions. If the sealed region is not rectangular, FDS will extend the specified {\ct ZONE} boundaries to conform to the non-rectangular region. It is possible to ``break'' pressure zones by removing obstructions between them. An example of how to break pressure zones is given below. Second, pressure zones can span multiple meshes, but it is recommended that you check the pressure in each mesh to ensure consistency. Also, if the {\ct ZONE} does span multiple meshes, make sure that the specified rectangular coordinates do so as well. This allows FDS to determine the actual extent of the {\ct ZONE} independently for each mesh. If the pressure zone has a non-rectangular shape such that it winds its way in and out of multiple meshes and you cannot create a single rectangular region to span it, you may use a series of points, one in each mesh touched by the pressure zone:
\begin{lstlisting}
&ZONE XYZ=1.0,2.0,2.3, 3.1,4.2,5.6, ... /
\end{lstlisting}
Each point should be clear of solid obstructions. A search algorithm will determine all other grid cells within the particular mesh belonging to that pressure zone.

Note that if you plan to have one zone open up to another via the removal of an obstruction, make sure that the coordinates of the two zones abut (i.e., touch) even if one of the zones includes the solid obstruction that separates them. FDS recognizes that a zone boundary has been removed when two adjacent cells belonging to two different zones have no solid obstruction between them. It is recommended that you extend at least one of the zone boundaries {\em into} the solid obstruction separating the two zones. That way, when the obstruction is removed, the newly created gas phase cells will be assigned to one or the other zone and it will become obvious that two adjacent gas phase cells are of two different zones, at which point the zones will merge and no longer have distinct background pressures.

For the special case where a zone has periodic boundaries ({\ct SURF\_ID='PERIODIC'} on {\ct VENT}), you must add {\ct PERIODIC=.TRUE.} on the {\ct ZONE} line.


\subsubsection{Example Case: Pressure Rise in a Compartment}
\label{pressure_rise}

This example tests several basic features of FDS. A narrow channel, 3~m long, 0.002~m wide, and 1~m tall, has air injected at a rate of 0.1~kg/m$^2$/s over an area of 0.2~m by 0.002~m for 60 s, with a linear ramp-up and ramp-down over 1 s. The total mass of air in the channel at the start is 0.00718~kg. The total mass of air injected is 0.00244~kg. The domain is assumed two-dimensional, the walls are adiabatic, and {\ct STRATIFICATION} is set to {\ct .FALSE.} simply to remove the slight change in pressure and density with height. The domain is divided into three meshes, each 1~m long and each with identical gridding.  We expect the pressure, temperature and density to rise during the 60~s injection period. Afterwards, the temperature, density, and pressure should remain constant, according to the equation of state. Figure~\ref{pressure_rise_fig} shows the results of this calculation.  The density matches exactly showing that FDS is injecting the appropriate amount of mass. The steady state values of the pressure, density and temperature are consistent with the ideal values obtained from the first law of thermodynamics.

\begin{figure}[ht]
\begin{tabular*}{\textwidth}{lr}
\includegraphics[height=2.2in]{SCRIPT_FIGURES/pressure_rise_T} &
\includegraphics[height=2.2in]{SCRIPT_FIGURES/pressure_rise_P} \\
\includegraphics[height=2.2in]{SCRIPT_FIGURES/pressure_rise_R} &
\end{tabular*}
\caption[Results of the {\ct pressure\_rise} test case]{Output of {\ct pressure\_rise} test case.}
\label{pressure_rise_fig}
\end{figure}


\subsubsection{Example Case: Breaking Pressure Zones}
\label{zone_break_slow}
\label{zone_break_fast}

In this example, three simple compartments are initially isolated from each other and from the ambient environment outside. Each compartment is a separate pressure zone. Air is blown into Zone~1 at a constant rate of 0.1~kg/s, increasing its pressure approximately 2000~Pa by 10~s, at which time Zone~1 is opened to Zone~2, decreasing the overall pressure in the two zones to roughly one-third the original value because the volume of the combined pressure zone has been roughly tripled. At 15~s, the pressure is further decreased by opening a door to Zone~3, and, finally, at 20~s the pressure returns to ambient following the opening of a door to the outside. Figure~\ref{zone_break} displays the pressure within each compartment.
\begin{figure}[ht]
\includegraphics[width=3.1in]{SCRIPT_FIGURES/zone_break_fast}
\includegraphics[width=3.1in]{SCRIPT_FIGURES/zone_break_slow}
\caption[Results of the {\ct zone\_break} test cases]{Output of {\ct zone\_break} test cases. The figure on the left results from using a pressure relaxation time of 0.5~s. The
figure on the right uses 1~s, the default.}
\label{zone_break}
\end{figure}
Notice that the pressures do not come to equilibrium instantaneously. Rather, the {\ct PRESSURE\_RELAX\_TIME} (on the {\ct PRES} line) is applied to bring the zones
into equilibrium over a specified period of time. This is done for several reasons. First, in reality doors and windows do not magically disappear as they do in FDS. It takes
a finite amount of time to fully open them, and the slowing of the pressure increase/decrease is a simple way to simulate the effect.
Second, relatively large pressure differences between zones wreak havoc with flow solvers, especially ones like FDS that
use a low Mach number approximation. To maintain numerical stability, FDS gradually brings the pressures into equilibrium. This second point ought to be seen as a warning.

Since pressure zones are defined using {\ct XB}, it might not be possible to define a complexly shaped set of pressure zones using just the {\ct ZONE} inputs.  A work around for this is to define the complex zone as a series of zones in the same manner you would divide a domain into multiple meshes.  The check for merged pressure zones only works if two zones were initially isolated at the start of the calculation (there must have been a wall that was removed). Therefore, define an obstruction at the boundary of the zones that is removed after the first time step.

Do not use FDS to study the sudden rupture of pressure vessels! Its low Mach number formulation does not allow for high speed, compressible effects that
are very important in such analyses. The zone breaking functionality described in this example is only intended to be used for relatively small pressure differences (<0.1~atm) between compartments. Real buildings cannot withstand substantially larger pressures anyway.

\subsubsection{Example Case: Irregularly Shaped Zone}
\label{zone_shape}

This example is similar to the ones in the previous section, except in this case, the pressure zone is L-shaped and split across two meshes. The objective is simply to ensure that the specification of the pressure zone is properly accounted for in the model. Figure~\ref{zone_shape_fig} compares the predicted pressure in the compartment compared to an exact solution. Air is injected into the compartment for 5~s, after which the compartment is opened to a smaller compartment. At 15~s, the smaller compartment is opened to the outside.

\begin{figure}[ht]
\centering
\includegraphics[width=3.1in]{SCRIPT_FIGURES/zone_shape}
\caption[Results of the {\ct zone\_shape} test case]{Output of {\ct zone\_shape} test case. Shown is the pressure in an L-shaped compartment that is opened to another compartment at 5~s, and the outdoors at 15~s.}
\label{zone_shape_fig}
\end{figure}



\subsection{Leaks}
\label{info:Leaks}

With a few notable exceptions, like containment buildings for nuclear power plants, real world construction is not air tight.  Small gaps occur along windows and doors and where walls abut each other and the floors and ceilings.  As a compartment is pressurized by a fire, air will escape through these small gaps.  This is referred to as leakage.

Leakage is inherently a sub-grid scale phenomenon because the leakage area is usually very small. In other words, it is not possible to define a leak directly on the
numerical mesh. It is sometimes possible to ``lump'' the leaks into a single mesh-resolvable hole, but this is problematic
for two reasons. First, the leakage area rarely corresponds neatly to the area of a single mesh cell-sized hole. Second, the
flow speeds through the hole can be large and cause numerical instabilities.

A better way to handle leakage is by exploiting the HVAC model. The compartment surface that is leaking can be thought of as a large HVAC vent that connects via a very small duct to the outside. This allows the leakage to be removed over a large area in the domain (just as it would be in reality) while correctly capturing the actual area of the leakage path. There are two approaches to this.  The first approach is by exploiting only pressure zones.  A pressure zone is a user-specified volume within the computational domain that is
entirely surrounded by solid obstructions. For example, the interior of a closed room can be, and should be, declared a pressure zone. In this approach surfaces within a pressure zone are denoted as leaking, and those surfaces can be considered an HVAC vent that connects to the outside via a tiny duct whose area is the leakage area. This leakage approach will prevent a compartment from seeing large pressure changes as fires grow and decay, but it cannot account for effects like exterior wind or the stack effect. The second approach is intended for leaks with well defined locations (a cracked open door where the crack size is subgrid) or for leaks where the stack effect is important. It uses the local pressure (which includes the zone pressure), which allows for leakage to vary in magnitude.

\subsubsection{Pressure Zone Leakage}
\label{info:zone_leakage}

The pressure zone leakage approach is intended to capture the bulk leakage that occurs through walls. This approach assumes that the amount of leaking gas is very small, and that it will exchange sufficient heat as it moves through a wall to be at the same temperature as the wall surface. With this approach the pressure between the source and destination zones is used to compute a leakage flow via the HVAC model. That flow is then uniformly imposed over all surfaces designated as part of the leakage path. The first step is to define pressure zones, leakage areas, and a description of the surfaces through which leaking occurs:
\begin{lstlisting}
&ZONE XB=..., LEAK_AREA(0)=0.0001 /
&ZONE XB=..., LEAK_AREA(1)=0.0002, LEAK_AREA(0)=0.0003 /
&SURF ID='LEAKY EXTERIOR WALL',..., LEAK_PATH=1,0 /
&SURF ID='LEAKY INTERIOR WALL',..., LEAK_PATH=1,2 /
\end{lstlisting}
The first line designates a region of the computational domain to be Pressure Zone~1. Note that the order of the {\ct ZONE} lines is important; that is, the order implicitly defines Zone~1, Zone~2, etc. Zone 0 is by default the ambient pressure exterior. In this example, a leak exists between Zone~1 and the exterior Zone~0, and the area of the leak is 0.0001~m$^2$ (1 cm by 1 cm hole, for example). Zone~2 leaks to Zone~1 (and vice versa) with a leak area of 0.0002~m$^2$. Zone~2 also leaks to the outside with an area of 0.0003~m$^2$. Note that zones need not be physically connected for a leak to occur, but in each zone, except for the exterior, there must be some surface with a designated {\ct LEAK\_PATH}. Here, in Zones~1 and 2 there are surfaces defined by both {\ct 'LEAKY EXTERIOR WALL'} and {\ct 'LEAKY INTERIOR WALL'} so as to provide a surface over which to apply the leakage. Leakage is uniformly distributed over all of the solid surfaces assigned the {\ct LEAK\_PATH}. The order of the two pressure zones designated by {\ct LEAK\_PATH} is unimportant, and the solid obstructions where the leakage is applied need not form a boundary between the two zones.

The volume flow, $\dot{V}$, through a leak of area $A_{\rm L}$ is given by
\be  \dot{V}_{\rm leak} = A_{\rm L} \; \hbox{sign} (\Delta p) \; \sqrt{2 \frac{ | \Delta p |}{\rho_\infty}} \ee
where $\Delta p$ is the pressure difference between the adjacent compartments (in units of Pa) and $\rho_\infty$ is the ambient density (in units of kg/m$^3$). The discharge coefficient normally seen in this type of formula is assumed to be 1.

In a typical building as the interior pressure rises, the leakage area will grow as small gaps, cracks, and other leakage paths open up. Leakage tests performed according to test standards such as ASTM~E~779 provide two additional data points to quantify this behavior. These are the {\ct LEAK\_PRESSURE\_EXPONENT} and the {\ct LEAK\_REFERENCE\_PRESSURE}. The use of these additional inputs are shown in the equation below as $n$ and $\Delta p_{\rm ref}$ respectively where $A_{\rm L,ref}$ is given by {\ct LEAK\_AREA}.
\be  A_{\rm L} = A_{\rm L,ref} \left( \frac{\Delta p}{\Delta p_{\rm ref}} \right)^{n-0.5} \ee
By default, $n=0.5$ and $\Delta p_{\rm ref}=4$~Pa, meaning that the leak area will not change with pressure unless you specify an exponent other than 0.5.

The HVAC output quantities can be used to determine the leakage flows. FDS names the duct connecting Zone~A with Zone~B {\ct 'LEAK A B'} and the duct nodes {\ct 'LEAK A B'} for the Zone~A side of the leak and {\ct 'LEAK B A'} for the Zone~B side.  Note that for the duct names, FDS will use the lower numbered zone as Zone~A.

FDS is limited by default to a maximum of 200 {\ct ZONE} inputs.  This can be increased if needed by the parameter {\ct MAX\_LEAK\_PATHS} on the {\ct MISC} line.

\subsubsection{Localized Leakage}
\label{info:local_leakage}

The local leakage approach is intended to represent leakage through a specific crack. For example, a cracked open door might have a opening that is too small to resolve with the grid.  One would; however, still want to capture the fact that hot gases could escape the top of the crack and cold gases enter the bottom. The local leakage approach uses the local pressure rather than just the zone pressure. Therefore, one can define multiple leakage paths for different windows, over the height of a door, or over the height of a tall stairwell where stack effect might be important. To use this approach two {\ct VENT} inputs are linked via an {\ct HVAC} input with {\ct TYPE\_ID='LEAK'}. In the example below a 0.001 m$^2$ leakage path is created between the {\ct VENT} with {\ct ID='VENT 1'} and the {\ct VENT} with {\ct ID='VENT 2'}. Note that the {\ct SURF\_ID} for a {\ct VENT} with localized leakage is not {\ct 'HVAC'}. The input must correspond to a {\ct SURF} input. Wall heat transfer will be computed based upon the inputs on the referenced {\ct SURF} input.
\begin{lstlisting}
&VENT XB=...,SURF_ID='SURF 1',ID='VENT 1'/
&VENT XB=...,SURF_ID='SURF 2',ID='VENT 2'/
&HVAC ID='LEAK1',TYPE_ID='LEAK',VENT_ID='VENT 1',VENT2_ID='VENT 2',AREA=0.001/
\end{lstlisting}
This will create a duct with the name {\ct 'LEAK1'} whose two nodes will be named {\ct VENT\_ID} and {\ct VENT2\_ID}. If the leakage path is to connect to the ambient outside the domain, then set {\ct VENT2\_ID='AMBIENT'}. In this case the second node will be the first node name with {\ct AMB} appended (e.g. {\ct 'VENT 1 AMB'}). Note that each {\ct VENT} must lie in one pressure zone; however, it may span more than one {\ct MESH}.

Unlike the zone leakage approach, this approach has the option to preserve the energy of the gas flowing through the leak. For example, for door crack using with pressure zone leakage, the outflowing gas at the top of the door would always be the same temperature as the outside of the door. To maintain hot gas flowing out of the leak, add {\ct LEAK\_ENTHALPY=.TRUE.} to the {\ct HVAC} input. For each outflowing wall cell, this will compute the enthalpy difference between the temperature of the leak flow and the temperature of the surface and add it as a source of heat to the adjacent gas cell.  The default value is {\ct LEAK\_ENTHALPY=.FALSE.}

This approach also has the option of changing the flow loss by specifying {\ct LOSS} on the {\ct HVAC} input.  The default is {\ct LOSS=1}; the same as for pressure zone leakage.

Note, for this approach it is not required that one have pressure zones defined; however, it is recommended to do so if different pressure zones do in fact exist in the model.

\subsubsection{Example Case: door\_crack}
\label{door_crack}

This example involves a small compartment that contains a fan in one wall and a closed door with leakage at its bottom in the opposite wall.
A small (160~kW) fire is added to the compartment. Initially, the pressure rises due to the heat from the fire and the fan blowing air into the compartment.
Eventually the pressure rise inside the compartment exceeds the maximum pressure of the fan, at which point the compartment begins to exhaust from both the fan and the leakage.
Pressure will continue to rise due to the fire until the pressure relief due to leakage and back flow through the fan equals the pressure increase from the fire.

\begin{figure}[ht]
\begin{tabular*}{\textwidth}{l@{\extracolsep{\fill}}r}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/door_crack_Pressure} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/door_crack_HRR}
\end{tabular*}
\caption[Results of the {\ct door\_crack} test case]{Output of {\ct door\_crack} test case. Symbols are expected values.}
\end{figure}





\section{Pressure Boundary Conditions}
\label{info:pressure_boundary}

In some situations, it is more convenient to specify a pressure, rather than a velocity, at a boundary. Suppose, for example, that you are modeling the
interior of a tunnel, and a wind is blowing at one of the portals that affects the overall flow within the tunnel. If (and only if) the portal is defined using an {\ct OPEN} vent, then the {\em dynamic pressure} at the boundary can be specified like this:
\begin{lstlisting}
&VENT XB=..., SURF_ID='OPEN', DYNAMIC_PRESSURE=2.4, PRESSURE_RAMP='wind' /
&RAMP ID='wind', T= 0.0, F=1.0 /
&RAMP ID='wind', T=30.0, F=0.5 /
            .
            .
\end{lstlisting}
The use of a {\em dynamic pressure} boundary affects the FDS algorithm as follows.  At {\ct OPEN} boundaries, the hydrodynamic pressure (head) $\cH$ is specified as
\begin{eqnarray}
\cH &=& \mbox{\ct DYNAMIC\_PRESSURE}/\rho_\infty + {|\mathbf{u}|^2}/2 \quad  \mbox{(outgoing)}  \nonumber \\
\cH &=& \mbox{\ct DYNAMIC\_PRESSURE}/\rho_\infty \quad                       \mbox{(incoming)}
\end{eqnarray}
where $\rho_\infty$ is the ambient density and $\mathbf{u}$ is the most recent value of the velocity on the boundary.
The {\ct PRESSURE\_RAMP} allows you to alter the pressure as a function of time. Note that you do not
need to ramp the pressure up or down starting at zero, like you do for various other ramps.
The net effect of a positive dynamic pressure at an otherwise quiescent boundary is to
drive a flow into the domain. However, a fire-driven flow of sufficient strength can push back against this incoming flow.

The following lines, taken from the sample case, {\ct pressure\_boundary}, demonstrates how to specify
a time-dependent pressure boundary at the end of a tunnel. The tunnel is 10~m long, 1~m wide, 1~m tall
with a fire in the middle and a pressure boundary imposed on the right side. The left side ({\ct XMIN}) is
just an {\ct OPEN} boundary with no pressure specified. It is assumed to be at ambient pressure.
\begin{lstlisting}
&VENT MB = 'XMIN' SURF_ID = 'OPEN' /
&VENT MB = 'XMAX' SURF_ID = 'OPEN', DYNAMIC_PRESSURE=2.4, PRESSURE_RAMP='wind_ramp' /
&RAMP ID='wind_ramp', T= 0., F= 1. /
&RAMP ID='wind_ramp', T=15., F= 1. /
&RAMP ID='wind_ramp', T=16., F=-1. /
\end{lstlisting}
Figure~\ref{pressure_boundary} shows two snapshots from Smokeview taken before and after the time when the positive pressure is imposed at the right portal of a tunnel. The fire leans to the left because of the preferential flow in that direction. It leans back to the right when the positive pressure is directed to become negative.

\begin{figure}[ht]
\includegraphics[width=\textwidth]{SCRIPT_FIGURES/pressure_boundary_left}
\includegraphics[width=\textwidth]{SCRIPT_FIGURES/pressure_boundary_right}
\caption[Snapshots of the {\ct pressure\_boundary} test case]{Snapshots from the sample case {\ct pressure\_boundary}
showing a fire in a tunnel leaning left, then right, due to a positive, then negative, pressure imposed at
the right portal.}
\label{pressure_boundary}
\end{figure}



\section{Special Flow Profiles}
\label{info:profiles}

By default, the air injected at a vent has a uniform or ``top hat'' velocity profile, but the parameter {\ct PROFILE} on the {\ct SURF} line can yield other profiles.

\subsubsection{Parabolic}
\label{parabolic_profile}

{\ct PROFILE='PARABOLIC'} produces a parabolic profile with {\ct VEL} (m/s) being the maximum velocity or {\ct VOLUME\_FLOW} (m$^3$/s) being the desired volume flow. As an example, the test case in the {\ct Flowfields} examples folder called {\ct parabolic\_profile.fds} demonstrates how you can create a circular or rectangular vent, each with a parabolic inlet profile. The two {\ct VENT} lines below create circular and rectangular inlets, respectively, each of which inject air (or the background gas) at a rate of 0.5~m$^3$/s {\em into} the compartment.
\begin{lstlisting}
&SURF ID='BLOW', VOLUME_FLOW=-0.5, PROFILE='PARABOLIC' /
&VENT SURF_ID='BLOW', XB=-3,1,-3,1,0,0, RADIUS=2., XYZ=-1,-1,0 /
&VENT SURF_ID='BLOW', XB= 3,5,-2,1,0,0 /
\end{lstlisting}
The purpose of the test case is to ensure that the proper amount of gas (in this case nitrogen) is forced into the compartment, as confirmed by the pressure rise. Figure~\ref{parabolic_profile_fig} displays a comparison of the calculated versus the exact pressure rise in a large compartment with these two parabolic vents. The pressure should rise according to the equation and analytical solution:
\be
   \frac{\d p}{\d t} = \frac{\gamma \, \dot{V}}{V} \, p   \quad \Longrightarrow \quad p(t) - p_0 = p_0 \left( {\rm e}^{\frac{\gamma \, \dot{V}}{V} \, t} - 1 \right)
\ee
where the ratio of specific heats, $\gamma=1.4$, volume flow rate, $\dot{V}=1$~m$^3$/s, volume, $V=4000$~m$^3$, and ambient pressure, $p_0=101325$~Pa. Note that to obtain this simple result, FDS was run with the option {\ct CONSTANT\_SPECIFIC\_HEAT\_RATIO} set to true.
\begin{figure}[ht]
\centering
\includegraphics[width=3.2in]{SCRIPT_FIGURES/parabolic_profile}
\caption[Results of the {\ct parabolic\_profile} test case]{Results of the {\ct parabolic\_profile} test case}
\label{parabolic_profile_fig}
\end{figure}




\subsubsection{Boundary Layer (Circular Vent)}

{\ct PROFILE='BOUNDARY LAYER'} may be used for circular vents created using {\ct RADIUS}. By adding {\ct VEL\_BULK} on the {\ct SURF} line together with {\ct VEL}, FDS will produce a plug flow core profile, with max velocity given by {\ct VEL}, and a quadratic profile in the boundary layer.  The form of the profile is illustrated in Fig.~\ref{fig:bl_profile} for a circular vent.  The functional form of the velocity profile (here taken a vertical profile) is
\begin{equation}
w(r) = \left\{ \begin{array}{ll} w_{\si{max}} & \quad \mbox{if} \quad r \le R-\delta \\ w_{\si{max}}\left(1 - \left(\frac{r-(R-\delta)}{\delta}\right)^2\right) & \quad \mbox{if} \quad R-\delta < r \le R \end{array} \right.
\end{equation}
The bulk velocity is the volumetric flow rate divided by the circular flow area.  {\ct VEL\_BULK} is negative pointing into the domain.  The boundary layer thickness is $\delta$.  This feature is handy for dealing with the case where the maximum velocity is higher than the bulk velocity.  Here is an example input file line:
\begin{lstlisting}
&SURF ID='JET', VEL=-69, VEL_BULK=-53, PROFILE='BOUNDARY LAYER', ... /
\end{lstlisting}

\begin{figure}[ht]
\begin{center}
\includegraphics[width=3.2in]{FIGURES/bl_profile}
\caption[Boundary layer profile]{Boundary layer profile.}
\label{fig:bl_profile}
\end{center}
\end{figure}




\chapter{Atmospheric Effects and Wind}

This chapter describes techniques for modeling the atmospheric boundary layer. Most of the parameters that describe the atmosphere are entered on a single namelist line called {\ct WIND}. This namelist group is new starting with FDS version 6.6.0. Previous versions of FDS used the {\ct MISC} line for parameters related to wind and atmospheric conditions.

There are three ways to specify a wind in FDS. The preferred method, originally implemented in FDS version 6.6.0, is to model the wind and corresponding temperature profile using Monin-Obukhov similarity theory (Section~\ref{info:WIND}). A second, more complicated method, is to specify a uniform horizontal forcing function and allow the wind field to develop naturally. This has proven more useful in wind tunnel applications than for natural winds (Section~\ref{info:force_vector}). The third method, which has traditionally been employed in older versions of FDS, is to create essentially a ``wall of wind'' where an entire side of the computational domain is turned into a giant fan blowing air laterally. This is the least preferred method of creating a wind (Section~\ref{info:wall_of_wind}).


\section{Wind Method 1: Monin-Obukhov Similarity}
\label{info:WIND}

\subsection{Basic Equations}

The atmospheric boundary layer in FDS is modeled using Monin-Obukhov similarity theory. The wind speed profile, $u$, and potential temperature\footnote{The potential temperature is given by $$\theta=T \left( \frac{p_0}{p} \right)^{R/(W_{\rm air} \, c_p)}$$ where $p_0$ is typically 1000~mbar and $R/(W_{\rm air} \, c_p) \approx 0.286$.}, $\theta$, vary with height, $z$, according to:
\begin{eqnarray}
   u(z)      &=&            \frac{u_*}{\kappa}     \left[ \ln \left( \frac{z}{z_0} \right) - \psi_{\rm m} \left( \frac{z}{L} \right) \right] \label{u_om} \\[.15in]
   \theta(z) &=& \theta_0 + \frac{\theta_*}{\kappa} \left[ \ln \left( \frac{z}{z_0} \right) - \psi_{\rm h} \left( \frac{z}{L} \right) \right]
\end{eqnarray}
where $u_*$ is the friction velocity, $\kappa=0.41$ is the Von K\'{a}rm\'{a}n constant, $z_0$ is the \emph{aerodynamic} roughness length, $\theta_*$ is the scaling potential temperature, $\theta_0$ is the ground level potential temperature, $L$ is the Obukhov length, and the similarity functions are those proposed by Dyer~\cite{Dyer:1974}:
\begin{eqnarray}
   \psi_{\rm m}\left(\frac{z}{L}\right) &=& \left\{ \begin{array}{c@{\quad:\quad}l} \displaystyle -5 \, \frac{z}{L} & L \ge 0 \\[.2in]  \displaystyle 2 \, \ln \left[\frac{1+\zeta}{2}\right] + \ln \left[\frac{1+\zeta^2}{2}\right]-2 \, \tan^{-1}(\zeta) + \frac{\pi}{2} & L<0 \end{array} \right.  \\[.2in]
   \psi_{\rm h}\left(\frac{z}{L}\right) &=& \left\{ \begin{array}{c@{\quad:\quad}l} \displaystyle -5 \, \frac{z}{L} & L \ge 0 \\[.2in]  \displaystyle 2 \, \ln \left[\frac{1+\zeta^2}{2}\right] & L<0 \quad \quad  \displaystyle \zeta=\left( 1 - \frac{16 \, z}{L} \right)^{1/4}  \end{array} \right.
\end{eqnarray}
The Obukhov length, $L$, characterizes the thermal stability of the atmosphere. When $L$ is negative, the atmosphere is unstably stratified; when positive, the atmosphere is stably stratified.  The stabilizing or destabilizing effects of stratification are strongest as $L$ nears zero.  Accordingly, a neutrally stratified atmosphere would have an infinite Obukhov length. Generally, an unstable atmosphere exhibits a decreasing temperature with height and relatively large fluctuations in wind direction/velocity. Unstable atmospheres are strongly affected by the buoyancy-generated turbulence, resulting in enhanced mixing.  Conversely, highly stable atmospheric conditions suppress turbulent mixing.

In the event that these various parameters are not reported or known, they can be estimated from the basic meteorological conditions. From just a single measured mean wind velocity, $u_{\rm ref}$, taken at a height, $z_{\rm ref}$, the friction velocity can be calculated from:
\be
   u_* = \frac{\kappa \, u_{\rm ref}}{\ln(z_{\rm ref}/z_0)}
\ee
The Obukhov length, $L$, can be chosen from Table~\ref{OL}. Suggested values of the aerodynamic roughness length\footnote{Note that \emph{aerodynamic} roughness, $z_0$, is not the same as \emph{sand grain} roughness, $s$, discussed in Sec.~\ref{info:WALL_MODEL}. For more information, see Section~\ref{aerodynamic_roughness}.}, $z_0$, are given in Table~\ref{z0}.
\begin{table}[!ht]
\centering
\caption[Suggested values of Obukhov length]{Suggested values of the Obukhov length, $L$ (m).}
\begin{tabular}{|l|c|c|} \hline
Stability           & Value Range            & Suggested Value  \\  \hline \hline
Very Unstable       & $-200 \le L < 0$       & $-100$           \\ \hline
Unstable            & $-500 \le L < -200$    & $-350$           \\ \hline
Neutral             & $|L|>500$              & $1000000$        \\ \hline
Stable              & $200 < L \le 500$      & $350$            \\ \hline
Very Stable         & $0 < L \le 200$        & $100$            \\ \hline
\end{tabular}
\label{OL}
\end{table}

\begin{table}[!ht]
\centering
\caption[Davenport-Wieringa roughness length classification]{Davenport-Wieringa roughness length classification~\cite{Stull:2000}.}
\begin{tabular}{|c|c|c|} \hline
$z_0$ (m)    & Classification    & Landscape  \\  \hline \hline
0.0002       & sea               & sea, paved areas, snow-covered flat plain, tidal flats, smooth desert \\ \hline
0.005        & smooth            & beaches, pack ice, snow-covered fields                                \\ \hline
0.03         & open              & grass prairie, farm fields, tundra, airports, heather                 \\ \hline
0.1          & roughly open      & low crops and occasional obstacles (single bushes)                    \\ \hline
0.25         & rough             & high crops, scattered obstacles such as trees or hedgerows, vineyards \\ \hline
0.5          & very rough        & mixed farm fields and forest clumps, orchards, scattered buildings    \\ \hline
1.0          & closed            & suburbs, villages, forests                                            \\ \hline
>2           & chaotic           & large towns and cities, irregular forests                             \\ \hline
\end{tabular}
\label{z0}
\end{table}

The scaling potential temperature, $\theta_*$, can be obtained from the relation:
\be
   \theta_* = \frac{u_*^2 \, \theta_0}{g \, \kappa \, L}
\ee
Alternatively, the scaling potential temperature can be estimated from the expression for the the sensible heat flux:
\be
   \dot{q}'' = \rho \, c_p \, u_* \, \theta_*
\ee
where a negative value indicates that the ground is warmer than the air above.

Figure~\ref{wind_profiles} displays a few sample wind profiles. Notice that the sign of $L$ determines whether the atmosphere is stable or unstable; that is, whether the temperature increases or decreases relative to the ground temperature.

\begin{figure}[p]
   \begin{tabular*}{\textwidth}{l@{\extracolsep{\fill}}r}
      \includegraphics[width=3.2in]{FIGURES/vel_L=-100}  &
      \includegraphics[width=3.2in]{FIGURES/tmp_L=-100}  \\
      \includegraphics[width=3.2in]{FIGURES/vel_L=100}  &
      \includegraphics[width=3.2in]{FIGURES/tmp_L=100}  \\
      \includegraphics[width=3.2in]{FIGURES/vel_L=-350}  &
      \includegraphics[width=3.2in]{FIGURES/tmp_L=-350}
   \end{tabular*}
   \caption[Sample vertical wind and temperature profiles]{Sample vertical wind and temperature profiles.}
   \label{wind_profiles}
\end{figure}


\subsection{Adding a Wind to FDS}


In simulations where wind and atmospheric effects are of interest, you usually have a limited amount of information about the conditions; typically a wind speed, direction, basic topography, and weather conditions. For example, for a southwesterly wind blowing 5~m/s over a relatively flat, rural landscape on a bright, sunny day, you could specify the following parameters:
\begin{lstlisting}
&WIND SPEED=5., DIRECTION=225., L=-100., Z_0=0.03 /

&VENT MB='ZMIN', SURF_ID='GROUND' /
&VENT MB='ZMAX', SURF_ID='OPEN' /
&VENT PBY=..., SURF_ID='PERIODIC', WIND=.TRUE. /
&VENT PBY=..., SURF_ID='PERIODIC', WIND=.TRUE. /
&VENT PBX=..., SURF_ID='PERIODIC', WIND=.TRUE. /
&VENT PBX=..., SURF_ID='PERIODIC', WIND=.TRUE. /
\end{lstlisting}
It is assumed here that the wind speed is taken at a height 2~m off the ground. If it is not, set {\ct Z\_REF} (m) accordingly. The wind {\ct DIRECTION} follows the usual meteorological convention---a northerly wind has direction of 0$^\circ$ and blows from north to south, or in the negative $y$ direction in the FDS coordinate system. An easterly wind has a direction of 90$^\circ$ and blows from east to west, or in the negative $x$ direction.

If you know the value of $u_*$ or $\theta_*$, you can input these on the {\ct WIND} line as {\ct U\_STAR} (m) and {\ct THETA\_STAR} (K). Otherwise, they will be computed from $L$ and $z_0$.

You may assign material properties to the {\ct GROUND} if you like, but be aware that FDS assumes the ground to be ambient temperature ({\ct TMPA}) initially, and the temperature of the atmosphere either increases or decreases with height according to the stability condition. The top of the domain is set to be {\ct 'OPEN'}, meaning that even though the wind field is more or less parallel to it, there might be, for example, a hot plume that can rise out of the computational domain.

The side boundaries of the domain can be set either to {\ct 'OPEN'} or {\ct 'PERIODIC'}. The former is the usual inflow/outflow condition; the latter assumes that the domain repeats itself endlessly in each direction. This is an important assumption because the turbulent atmospheric boundary layer that is modeled using Monin-Obukhov similarity theory is assumed to develop over distances far beyond the computational domain. The extra parameter on the {\ct VENT} line, {\ct WIND=.TRUE.}, directs FDS to mirror the basic meteorological conditions in all directions, but to not mirror smoke plumes, gas dispersion, etc., that you might create in your fire scenario. That is, you do not want a smoke plume that exits the eastern boundary of the domain to reappear instantly at the western boundary.

\subsubsection{Example Wind Simulation}
\label{wind_example}

An input file called {\ct wind\_example.fds} in the {\ct Atmospheric\_Effects} folder provides an example of a wind simulation. The computational domain is a flat landscape that is 1~km by 1~km by 100~m high. There are various rectangular blocks scattered about to represent buildings. The wind speed varies with height as shown in the first plot of Fig.~\ref{wind_profiles}. The wind also turns a full 360$^\circ$ in 50~s, starting and ending in the westerly direction (270$^\circ$). This turn of the wind is not realistic, but this case is intended to test the ramp and mean forcing functionality. The plots in Fig.~\ref{wind_example_fig} display some results of the simulation. On the left is a plot showing the mean velocity components of the simulated wind field compared to the specified (ideal) values. Notice that the simulated wind field lags the specified field by roughly 1~s because the relaxation parameter {\ct DT\_MEAN\_FORCING} is set to 1~s by default. The right hand plot of Fig.~\ref{wind_example_fig} displays the specified vertical wind speed profile compared to the simulation after the wind has turned full circle. The two profiles should be roughly aligned to indicate that the lateral boundary conditions of the mean forcing scheme are working properly.

\begin{figure}[ht]
\includegraphics[width=3.2in]{SCRIPT_FIGURES/wind_example_time}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/wind_example_prof}
\caption[Results of the {\ct wind\_example} test case]{(Left) Mean velocity components of the wind vs. the specified values. (Right) Simulated vs. specified vertical wind speed profile.}
\label{wind_example_fig}
\end{figure}


\subsection{Temporal and Spatial Variation of the Wind}

The velocity components {\ct U0}, {\ct V0}, and {\ct W0} (or the velocity magnitude, {\ct SPEED}) can be made functions of time and/or height using the {\ct RAMP} functions: {\ct RAMP\_DIRECTION}, {\ct RAMP\_U0\_T}, {\ct RAMP\_V0\_T}, or {\ct RAMP\_W0\_T} to vary the wind direction or its velocity components with time; and {\ct RAMP\_U0\_Z}, {\ct RAMP\_V0\_Z}, and {\ct RAMP\_W0\_Z} to vary the velocity components with height. For example,
\begin{lstlisting}
&RAMP ID='t-ramp', T=  0., F=0. /
&RAMP ID='t-ramp', T=100., F=1. /

&RAMP ID='z-ramp', Z=  0., F=1.0 /
&RAMP ID='z-ramp', Z=200., F=1.5 /
&RAMP ID='z-ramp', Z=500., F=1.8 /
\end{lstlisting}
The parameter {\ct F} represents the fraction of the specified velocity component as a function of time {\ct T} (s) or height {\ct Z} (m). Note that if you use Monin-Obukhov similarity parameters, you need not specify the vertical profile of the wind. It will be calculated automatically.

\subsection{Aerodynamic Roughness}
\label{aerodynamic_roughness}

The \emph{aerodynamic} roughness length, $z_0$, is not the same as the \emph{sand grain} roughness, $s$, discussed in Sec.~\ref{info:WALL_MODEL}. The default wall model used in FDS, in the ``fully rough'' limit, is given by the following log law:
\be
   \frac{u(z)}{u_*} = \frac{1}{\kappa} \, \ln \left( \frac{z}{s} \right) + 8.5
\ee
For the purpose of implementing the Monin-Obukhov model within FDS, the velocity profile given by Eq.~(\ref{u_om}) near the ground where $\psi_{\rm m} \approx 0$ can be superimposed, leading to the effective translation of roughness factors:
\be
   s = z_0 \, {\rm e}^{8.5 \, \kappa} \approx 30 \, z_0
\ee
To explicitly assert this relationship, you may set the {\ct ROUGHNESS} (m) on the {\ct SURF} line applied to the ground to be 30 times your chosen value of $z_0$.

\subsection{Sensible Heat Flux}

The ground temperature relative to the air temperature is an important consideration in ground level gas dispersion because it essentially defines the stability of the atmospheric boundary layer. Cold air blowing over a warm ground surface leads to greater dispersion than warm air blowing over cold ground. In FDS wind simulations, the ground temperature is assumed to be fixed at the specified ambient temperature {\ct TMPA}, and the choice of Monin-Obukhov parameters dictate the temperature profile of the atmosphere.  According to the model, the sensible heat flux is given by
\be
   \dot{q}_{\rm c}'' = \rho \, c_p \, u_* \theta_*
\ee
where a negative value indicates that the ground is warmer than the air above. In the simulation, you can explicitly specify the {\ct CONVECTIVE\_HEAT\_FLUX} (kW/m$^2$) on the {\ct SURF} line to be $-\dot{q}_{\rm c}''$. Note that $\rho$ (kg/m$^3$) is the density of air near the ground and $c_p$ is the specific heat of air near the ground, approximately 1~kJ/(kg$\cdot$K).

\subsection{Shielding Indoor Volumes from the Wind}
\label{info:BLOCK_WIND}

There is no sense of ``indoor'' or ``outdoor'' in an FDS simulation; there are only grid cells that are solid or not solid. Thus, a wind field will be induced everywhere in the computational domain. You may omit a region of the flow domain from the wind using the {\ct HOLE} feature. For example, to block the wind from a given volume, add a line of the form:
\begin{lstlisting}
&HOLE XB=4,8,2,7,0,5, BLOCK_WIND=.TRUE. /
\end{lstlisting}

\subsection{The Mean Forcing Concept}
\label{info:SPONGE_CELLS}

The process of steering the solution of the mass, momentum, and energy equations to match wind speed and direction gathered at random weather stations is known as \emph{data assimilation}~\cite{Kalnay:2003}. FDS uses a relatively simple data assimilation technique, a method known as \emph{nudging}, where you add a mean forcing term to the momentum equation to ``nudge'' the flow in the direction of the specified wind.  Currently, FDS can only affect the mean flow velocities. If you specify a wind {\ct SPEED} on the {\ct WIND} line, FDS will automatically drive the mean velocity components toward the desired values by adding a forcing term to the momentum equation:
\be
   \dod{u_i}{t} + \ldots = \frac{u_{i,{\rm spec}}(z,t)-\overline{u_i}}{\tau}
\ee
Here, $u_i$ is the computed velocity component, $u_{i,{\rm spec}}$ is the specified wind field component that can vary with height and time, and $\overline{u_i}$ is the average of the computed velocity component at the height $z$. The relaxation time scale, $\tau$, is an input parameter called {\ct DT\_MEAN\_FORCING} whose default value is 1~s. The shorter this time scale, the faster the flow field will ``catch up'' to the mean wind, but at the expense of possibly washing out important flow structures. Try several values of this time scale for your particular simulation to determine what is appropriate for your case. There is no firm guidance in the atmospheric modeling literature.

Note that if instead of specifying the wind {\ct SPEED}, you specify its components, {\ct U0} and {\ct V0} (rarely would you use {\ct W0}), FDS will {\em not} automatically assert mean forcing, but rather just initialize the flow field to these constant values of velocity. If you want to override this behavior, you can direct FDS to assert meaning forcing in all coordinate directions by setting {\ct MEAN\_FORCING=.TRUE.}, or you can assert mean forcing in the $x$, $y$, or $z$ directions using {\ct MEAN\_FORCING(N)=.TRUE.} where {\ct N} is set to 1, 2, or 3, respectively.

When simulating a wind with {\ct OPEN} boundaries, you might notice spurious velocity patterns at the downstream edge of the computational domain. These are artifacts related to the mean forcing function and the application of open boundary conditions at the external faces of the domain. To reduce spurious artifacts at external open wind boundaries, FDS forces both the normal and tangential components of the velocity towards that of the mean wind field at the side and top boundaries, which is why you should ensure that your obstructions are reasonably far from the boundaries. Some suggest that the top, upstream, and lateral boundaries extend outward 5 times the characteristic height of the buildings, and the downstream boundary extend 15 times the height. It is also suggested that the cross sectional area of obstructions be less than 3~\% of the total cross sectional area. However, these recommendations might be overly restrictive. It is suggested that you investigate different domain dimensions to ensure that they do not affect the outcome of your simulation. If you see spurious flow activity at external boundaries, consider increasing the ``sponge layer'' that FDS automatically builds around the exterior lateral boundaries. There is a parameter called {\ct SPONGE\_CELLS}, which is the number of grid cells at the exterior boundary where FDS aggressively forces the velocity to conform with the mean wind field. Within the domain interior, the ``nudging'' or mean forcing is less aggressive. The default value of {\ct SPONGE\_CELLS} is 3, meaning that aggressive forcing is employed in the nearest 3 grid cells adjacent to the $x$ and $y$ exterior boundaries.



\section{Wind Method 2: Letting the Wind Develop Naturally}
\label{info:force_vector}

Similar to the mean forcing feature, you may specify a constant and uniform force per unit volume by setting {\ct FORCE\_VECTOR(1:3)} on the {\ct WIND} line.  This is useful, for example, in specifying a mean pressure drop in a duct.  In the absence of other forces, the force vector $F_i$ affects the momentum equation by
\begin{equation}
\frac{\partial u_i}{\partial t} + \dots = -F_i/\rho
\end{equation}
This feature is typically used together with periodic boundaries.  To specify a mean pressure drop of 0.01 Pa/m in the $x$ direction for a periodic duct, for example, use
\begin{lstlisting}
&WIND FORCE_VECTOR(1)=0.01 /
&VENT MB='XMIN', SURF_ID='PERIODIC' /
&VENT MB='XMAX', SURF_ID='PERIODIC' /
\end{lstlisting}
You may apply a time ramp to {\ct FORCE\_VECTOR(1)}, for example, via {\ct RAMP\_FVX\_T} on the {\ct WIND} line.



\section{Wind Method 3: The ``Wall of Wind''}
\label{info:wall_of_wind}

An alternative to using Monin-Obukhov similarity theory in specifying a wind is to specify a power law wind profile at an external boundary of the computational domain. This essentially creates a ``wall of wind'' and for early versions of FDS it was the recommended method for specifying a wind. However, the techniques described above are preferable because they handle the lateral boundaries of the computational domain in a more natural way.

To specify a ``wall of wind'', set {\ct PROFILE='ATMOSPHERIC'} on the {\ct SURF} line that is assigned to an exterior lateral boundary of the computational domain. This generates a power law atmospheric wind profile of the form $u=u_0 (z/z_0)^p$ where $z$ is the height above the ground. If an atmospheric profile is prescribed, also prescribe {\ct Z0} for $z_0$  and {\ct PLE} for $p$. {\ct VEL} specifies the reference velocity $u_0$. Note that $z_0$ is not the ground, but rather the height above the ground where the wind speed is measured, like an elevated weather station. It is assumed that the ground is located at 0~m; to change this assumption, set {\ct GROUND\_LEVEL} on the {\ct WIND} line to be the appropriate elevation. Be careful not to apply an atmospheric velocity profile (e.g. negative $z$) below {\ct GROUND\_LEVEL} or FDS will stop with an error

Sometimes when using a wall of wind, you may want to initialize the flow to the chosen wind speed throughout the domain, but you may not want this initial wind field to persist indefinitely. In such cases, specify your initial flow components {\ct U0}, {\ct V0}, and/or {\ct W0} directly and do not use the parameter {\ct SPEED}. Setting the velocity components directly will initialize the simulation with a constant flow field, but the flow field will die off unless you add a blower somewhere in the domain.





\section{Temperature Stratification without Wind}
\label{info:stratification}

Typically, in the first few hundred meters of the atmosphere, the temperature decreases several degrees Celsius per kilometer. This small temperature change is important when considering the rise of smoke since the temperature of the smoke decreases rapidly as it rises. The {\ct LAPSE\_RATE} of the atmosphere can be specified on the {\ct WIND} line in units of $^\circ$C/m. A negative sign indicates that the temperature {\em decreases} with height. This need only be set for outdoor calculations where the height of the domain is tens or hundreds of meters. The default value of the {\ct LAPSE\_RATE} is 0~$^\circ$C/m.

Alternatively, you can specify {\ct RAMP\_TMP0\_Z} on the {\ct WIND} line if you want a non-linear change in temperature with height. For example,
\begin{lstlisting}
&WIND ..., RAMP_TMP0_Z='T profile', ...  /

&RAMP ID='T profile', Z= 0.001 , F= 1.0258  /
&RAMP ID='T profile', Z= 0.500 , F= 1.0019  /
&RAMP ID='T profile', Z= 1.000 , F= 1.0000  /
&RAMP ID='T profile', Z= 1.900 , F= 0.9986  /
&RAMP ID='T profile', Z= 3.000 , F= 0.9977  /
&RAMP ID='T profile', Z= 4.000 , F= 0.9972  /
\end{lstlisting}
The value of {\ct Z} is the height (m) above the ground. The value of {\ct F} is the ratio of the temperature at the given height in degrees K to the ambient temperature in degrees K, {\ct TMPA}+273.

By default, FDS assumes that the density and pressure decrease with height, regardless of the application or domain size. For most simulations, this effect is negligible, but it can be turned off completely by setting {\ct STRATIFICATION=.FALSE.} on the {\ct WIND} line.

\subsection{Stack Effect}
\label{info:stackeffect}
\label{stack_effect}

Tall buildings often experience buoyancy-induced air movement due to temperature differences between the interior and exterior, known as {\em stack effect}~\cite{Klote_Milke}. These temperature differences create flows within vertical shafts (stairwells, atriums, elevator shafts, etc.) due to leaks or openings at different levels. To simulate this phenomenon in FDS, you must include the entire building, or a substantial fraction of it, both inside and out, in the computational domain. It is important to capture the pressure and density decrease in the atmosphere based on the specified temperature profile that is entered on the {\ct WIND} line.

For the case where the stack flow is through small leakage paths, divide the building into one or more pressure {\ct ZONE}s. The leakage paths can be defined in terms of HVAC components. Note that the leakage model combines all leaky surfaces over the entire height of the building and as a result averages out the pressure gradients. For doing stack effect calculations individual leakage paths should be defined. A simple example is described next.

\subsubsection{Example Case: Atmospheric\_Effects/stack\_effect}

The {\em stack\_effect} test case is a two-dimensional simulation of a 100~m tall building whose interior air temperature is slightly warmer than its exterior. The building has leakage paths at the top and ground floors only. Since the inside air temperature is slightly warmer, the inside air pressure is slightly higher as well, and it drives air out of the building and in turn draws air into the building at the ground level.
The interior air temperature, $T_{\rm b}$, is initially 20~$^\circ$C (293~K), and the exterior air temperature, $T_\infty$, is
10~$^\circ$C (283~K). The {\ct LAPSE\_RATE} is set to 0~$^\circ$C/m; thus, $T_0(z)=T_\infty$ outside the building and $T_0(z)=T_{\rm b}$ inside the building. Two small leakage openings are defined 2.5~m above the ground floor and 2.5~m below the roof using the HVAC solver. Each opening is given an area of 0.01~m$^2$ and a loss coefficient of 2 (e.g., an entrance loss into the leak path of 1 and and exit loss out of the leak path of 1 both of which represent a sharp edge opening).

The initial density stratification inside and outside the building can be calculated using the relation:
\be
  \frac{\rho_0(z)}{\rho_\infty} = \exp \left(- \frac{g \overline{W}}{\R T_0} z \right)
\ee
where $\R$ is the universal gas constant, $g$ is the acceleration of gravity, and $\overline{W}$ is the average molecular weight of the air, $z$ is the height above the {\ct GROUND\_LEVEL}, and $T_0$ is the ambient temperature. Applying this formula to the external and internal locations at the lower and upper vents results in densities of 1.2412, 1.1989, 1.2272, and 1.1858~kg/m$^3$, respectively.

Since the openings in the building are equally spaced over its height, the neutral plane should be close to its midpoint. This can be computed from:
\be
  \frac{\Delta H }{H_{\rm n}} = 1 + \frac{T_{\rm b}}{T_\infty}
\ee
where $H_{\rm n}$ is the neutral plane height above the bottom vent and $\Delta H=95$~m is the distance between the leak points. This gives a neutral plane of 46.68~m above the lower vent or 49.18~m above the bottom of the building. Note that this is close to the midpoint value of 50~m above the bottom of the building. The pressure difference across the building's wall is computed from
\be
   \Delta p = \frac{\overline{W} \, p_0(z) \, g \, \Delta z} \R \left( \frac{1}{T_\infty} - \frac{1}{T_{\rm b}} \right)
\ee
where $ \Delta z$ is the distance from the leak point to the neutral plane.  Using the neutral plane location, the $ \Delta z$ values are -46.68~m for the lower vent and +48.32~m for the upper vent which respectively result in lower and upper vent pressure differences of -19.4~Pa and +20.4~Pa.  Using the loss of 2 and the pressure difference in the HVAC momentum equation results in a steady-state inflow velocity at the bottom of 3.95~m/s and an outflow velocity at the top of 4.15~m/s. Results for velocity and density are shown in Fig.~\ref{fig_stack_effect}.

\begin{figure}[t]
   \begin{tabular*}{\textwidth}{l@{\extracolsep{\fill}}r}
      \scalebox{1}{ \includegraphics[width=3.2in]{SCRIPT_FIGURES/stack_effect_v} } &
      \scalebox{1}{ \includegraphics[width=3.2in]{SCRIPT_FIGURES/stack_effect_rho} }
   \end{tabular*}
   \caption[Results of the {\ct stack\_effect} test case]{(Left) Velocity at the upper and lower vents for the {\ct stack\_effect} case.  (Right) Upper and lower exterior and interior densities.}
   \label{fig_stack_effect}
\end{figure}









\chapter{User-Specified Functions}
\label{info:RAMP}

Many of the parameters specified in the FDS input file are fixed constants. However, there are several parameters that may vary in time, temperature, or space. The namelist groups, {\ct RAMP} and {\ct TABL}, allow you to control the behavior of these parameters.  {\ct RAMP} allows you to specify a function with one independent variable (such as time) and one dependent variable (such as velocity). {\ct TABL} allows you to specify a function of multiple independent variables (such as a solid angle) and multiple dependent variables (such as a sprinkler flow rate and droplet speed).



\section{Time-Dependent Functions}
\label{info:RAMP_Time}

At the start of any calculation, the temperature is ambient everywhere, the flow velocity is zero everywhere, nothing is burning, and the mass fractions of all species are uniform.  When the calculation starts temperatures, velocities, burning rates, etc., are ramped-up from their starting values because nothing can happen instantaneously. By default, everything is ramped-up to their prescribed values in approximately 1~s\footnote{You can change the default ramp-up time by setting {\ct TAU\_DEFAULT} on the {\ct MISC} line. It is 1~s, by default.}. However, you can control the rate at which things turn on, or turn off, by specifying time histories either with pre-defined functions or with user-defined functions.  The parameters {\ct TAU\_Q}, {\ct TAU\_T}, and {\ct TAU\_V} indicate that the heat release rate ({\ct HRRPUA}); surface temperature ({\ct TMP\_FRONT}); and/or normal velocity ({\ct VEL}, {\ct VOLUME\_FLOW}), or {\ct MASS\_FLUX\_TOTAL} are to ramp up to their prescribed values in {\ct TAU} seconds and remain there. To prescribe different heat release rate ramps, the {\ct TAU\_Q} parameter can be defined as a negative value ($t$-squared growth rate) or a positive value ($\tanh$ growth rate), which results in a time-dependent heat release rate as
\begin{equation}
\dot Q(t) = \left\{ \begin{array}{ll} \dot Q_0 \left( \frac{t}{\tau} \right)^2            &  \mbox{if {\ct TAU\_Q} is negative} \\[.1in]
                                      \dot Q_0 \cdot \tanh \left( \frac{t}{\tau} \right)  &  \mbox{if {\ct TAU\_Q} is positive}  \end{array} \right.
\end{equation}
where $\dot Q_0$ is the user-specified heat release rate. If the fire ramps up following a $t$-squared curve, then it remains constant after {\ct TAU\_Q} seconds.  These rules apply to {\ct TAU\_T} and {\ct TAU\_V} as well. The default value for all {\ct TAU}s is 1~s.  If something other than a tanh or $t$-squared ramp up is desired, then a user-defined function must be input. To do this, set {\ct RAMP\_Q}, {\ct RAMP\_T} or {\ct RAMP\_V} equal to a character string designating the ramp function to use for that particular surface type, then somewhere in the input file generate lines of the form:
\begin{lstlisting}
 &RAMP ID='rampname1', T= 0.0, F=0.0 /
 &RAMP ID='rampname1', T= 5.0, F=0.5 /
 &RAMP ID='rampname1', T=10.0, F=0.7 /
\end{lstlisting}
Here, {\ct T} is the time, and {\ct F} indicates the fraction of the heat release rate, wall temperature, velocity, mass fraction, etc., to apply. Linear interpolation\footnote{By default, FDS uses a linear interpolation routine to find time or temperature-dependent values between user-specified points. The default number of interpolation points is 5000, more than enough for most applications. However, you can change this value by specifying {\ct NUMBER\_INTERPOLATION\_POINTS} on any {\ct RAMP} line.} is used to fill in intermediate time points. Note that each set of {\ct RAMP} lines must have a unique {\ct ID} and that the lines must be listed with monotonically increasing {\ct T}. Note also that the {\ct TAU}s and the {\ct RAMP}s are mutually exclusive. For a given surface quantity, both cannot be prescribed. As an example, a simple blowing vent can be controlled via the lines:
\begin{lstlisting}
&SURF ID='BLOWER', VEL=-1.2, TMP_FRONT=50., RAMP_V='BLOWER RAMP', RAMP_T='HEATER RAMP' /
&RAMP ID='BLOWER RAMP', T= 0.0, F=0.0 /
&RAMP ID='BLOWER RAMP', T=10.0, F=1.0 /
&RAMP ID='BLOWER RAMP', T=80.0, F=1.0 /
&RAMP ID='BLOWER RAMP', T=90.0, F=0.0 /
&RAMP ID='HEATER RAMP', T= 0.0, F=0.0 /
&RAMP ID='HEATER RAMP', T=20.0, F=1.0 /
&RAMP ID='HEATER RAMP', T=30.0, F=1.0 /
&RAMP ID='HEATER RAMP', T=40.0, F=0.0 /
\end{lstlisting}
Use {\ct TAU\_T} or {\ct RAMP\_T} to control the ramp-ups for surface temperature. The surface temperature at time $t$, $T_{\rm w}(t)$, is
\be
   T_{\rm w}(t) = T_0 + f(t) \left( {\ct TMP\_FRONT} - T_0 \right)
\ee
where $f(t)$ is the result of evaluating the {\ct RAMP\_T} at time $t$, $T_0$ is the ambient temperature, and {\ct TMP\_FRONT} is specified on the same {\ct SURF} line as {\ct RAMP\_T}. Use {\ct TAU\_MF(N)} or {\ct RAMP\_MF(N)} to control the ramp-ups for either the mass fraction or mass flux of species {\ct N}. For example:
\begin{lstlisting}
&SURF ID='...', MASS_FLUX(1:2)=0.1,0.3, SPEC_ID(1:2)='ARGON','NITROGEN',
      TAU_MF(1:2)=5.,10. /
\end{lstlisting}
indicates that argon and nitrogen are to be injected at rates of 0.1~\si{kg/(m$^2$.s)} and 0.3~\si{kg/(m$^2$.s)} over time periods of approximately 5~s and 10~s, respectively.

Table~\ref{tau_table} lists the various quantities that can be controlled by {\ct RAMP}s.


\begin{table}[ht]
\caption[Parameters used to control time-dependence]{Parameters for controlling the time-dependence of given quantities.}
\label{tau_table}
\begin{center}
\begin{tabular}{|l|l|l|l|l|}
\hline
Quantity            & Group       & Input Parameter(s)                                      & {\ct TAU}           & {\ct RAMP ID}       \\ \hline \hline
Volume Flow   & {\ct HVAC}  & {\ct VOLUME\_FLOW}                                        & {\ct TAU\_FAN}      & {\ct RAMP\_ID}       \\ \hline
Heating Rate   & {\ct HVAC}  & {\ct FIXED\_Q}                                            & {\ct TAU\_AC}        & {\ct RAMP\_ID}       \\ \hline
Heat Release Rate   & {\ct SURF}  & {\ct HRRPUA}                                            & {\ct TAU\_Q}        & {\ct RAMP\_Q}       \\ \hline
Heat Flux           & {\ct SURF}  & {\ct NET\_HEAT\_FLUX}, etc.                                            & {\ct TAU\_Q}        & {\ct RAMP\_Q}       \\ \hline
Temperature         & {\ct SURF}  & {\ct TMP\_FRONT}                                        & {\ct TAU\_T}        & {\ct RAMP\_T}       \\ \hline
Velocity            & {\ct SURF}  & {\ct VEL}                                               & {\ct TAU\_V}        & {\ct RAMP\_V}       \\ \hline
Volume Flux         & {\ct SURF}  & {\ct VOLUME\_FLOW}                                      & {\ct TAU\_V}        & {\ct RAMP\_V}       \\ \hline
Mass Flux           & {\ct SURF}  & {\ct MASS\_FLUX\_TOTAL}                                 & {\ct TAU\_V}        & {\ct RAMP\_V}       \\ \hline
Mass Fraction       & {\ct SURF}  & {\ct MASS\_FRACTION(N)}                                 & {\ct TAU\_MF(N)}    & {\ct RAMP\_MF(N)}   \\ \hline
Mass Flux           & {\ct SURF}  & {\ct MASS\_FLUX(N)}                                     & {\ct TAU\_MF(N)}    & {\ct RAMP\_MF(N)}   \\ \hline
Particle Mass Flux  & {\ct SURF}  & {\ct PARTICLE\_MASS\_FLUX}                              & {\ct TAU\_PART}     & {\ct RAMP\_PART}    \\ \hline
External Heat Flux  & {\ct SURF}  & {\ct EXTERNAL\_FLUX}                                    & {\ct TAU\_EF}       & {\ct RAMP\_EF}      \\ \hline
Pressure            & {\ct VENT}  & {\ct DYNAMIC\_PRESSURE}                                 &                     & {\ct PRESSURE\_RAMP}\\ \hline
Flow                & {\ct PROP}  & {\ct FLOW\_RATE}                                        & {\ct FLOW\_TAU}     & {\ct FLOW\_RAMP}    \\ \hline
Gravity             & {\ct MISC}  & {\ct GVEC(1)}                                           &                     & {\ct RAMP\_GX}      \\ \hline
Gravity             & {\ct MISC}  & {\ct GVEC(2)}                                           &                     & {\ct RAMP\_GY}      \\ \hline
Gravity             & {\ct MISC}  & {\ct GVEC(3)}                                           &                     & {\ct RAMP\_GZ}      \\ \hline
\end{tabular}
\end{center}
\end{table}

\section{Temperature-Dependent Functions}
\label{info:RAMP_Temperature}

Thermal properties like conductivity and specific heat can vary significantly with temperature. In such cases, use
the {\ct RAMP} function like this:
\begin{lstlisting}
&MATL ID                 = 'STEEL'
      FYI                = 'A242 Steel'
      SPECIFIC_HEAT_RAMP = 'c_steel'
      CONDUCTIVITY_RAMP  = 'k_steel'
      DENSITY            = 7850. /

&RAMP ID='c_steel', T= 20., F=0.45   /
&RAMP ID='c_steel', T=377., F=0.60   /
&RAMP ID='c_steel', T=677., F=0.85   /

&RAMP ID='k_steel', T= 20., F=48.    /
&RAMP ID='k_steel', T=677., F=30.    /
\end{lstlisting}
Note that for temperature ramps, as opposed to time ramps, the parameter {\ct F} is the actual physical quantity, not just
a fraction of some other quantity. Thus, if {\ct CONDUCTIVITY\_RAMP} is used, there should be no
value of {\ct CONDUCTIVITY} given. Note also that for values of temperature, {\ct T}, below and above the
given range, FDS will assume a constant value equal to the first or last {\ct F} specified. Note also that the {\ct DENSITY} of a material cannot be controlled with a {\ct RAMP} function.


\section{Spatially-Dependent Velocity Profiles}
\label{info:RAMP_Vel_Prof}

Similar to using {\ct PROFILE=`ATMOSPHERIC'} on {\ct SURF}, it is possible to specify {\ct PROFILE=`RAMP'} to generate 1D or 2D profiles of the normal component of velocity on a surface.  The following code generates a $u(z)$ profile on the {\ct `XMIN'} boundary.

\begin{lstlisting}
&SURF ID='inlet', VEL=-7.72, PROFILE='RAMP', RAMP_V_Z='u_prof' /
&VENT MB='XMIN', SURF_ID='inlet'/

&RAMP ID='u_prof', T=0.,      F=0.   /
&RAMP ID='u_prof', T=0.0098,  F=0.   /
&RAMP ID='u_prof', T=0.01005, F=0.2474 /
&RAMP ID='u_prof', T=0.01029, F=0.4521 /
&RAMP ID='u_prof', T=0.01077, F=0.6256 /
&RAMP ID='u_prof', T=0.01174, F=0.7267 /
&RAMP ID='u_prof', T=0.01368, F=0.8238 /
&RAMP ID='u_prof', T=0.01562, F=0.8795 /
&RAMP ID='u_prof', T=0.01756, F=0.9378 /
&RAMP ID='u_prof', T=0.0195,  F=0.9663 /
&RAMP ID='u_prof', T=0.02144, F=0.9922 /
&RAMP ID='u_prof', T=0.02338, F=0.9987 /
&RAMP ID='u_prof', T=0.02532, F=1 /
&RAMP ID='u_prof', T=0.0588,  F=1 /
\end{lstlisting}

Note that {\ct V} indicates the velocity component normal to the surface.  You can also specify {\ct RAMP\_V\_X} and {\ct RAMP\_V\_Y} and add these to the {\ct SURF}.  Note that only profiles in the planar directions will affect a given surface.  That is, if the surface is oriented in the $y-z$ plane, only {\ct RAMP\_V\_Y} and {\ct RAMP\_V\_Z} apply.  In the {\ct RAMP} definition {\ct T} is the independent variable and {\ct F} is the dependent variable.  In this example, {\ct T} is the $z$ coordinate in meters and {\ct F} is the factor multiplying {\ct VEL} on the {\ct SURF} line.  Two ramps may be applied to a surface.

{\ct T} does not need to be directly related to the FDS mesh.  The velocity points will be interpolated linearly by the ramp function.  In fact, this functionality is convenient for taking experimental data directly as a boundary condition to FDS.  You basically just need to list {\ct T} and {\ct F} from the data (you can set {\ct VEL=-1} if you want).  The results for this particular case are included under the heading ``Backward Facing Step'' in the FDS Validation Guide~\cite{FDS_Validation_Guide}. In this problem, the step height is $h=0.0098$ m, and the specification of the inlet profile is critical to correctly matching the reattachment point downstream of the step.


\section{Rotation and Translation}
\label{info:MOVE}

It is possible to rotate and/or translate various objects within an FDS simulation using the namelist group called {\ct MOVE}. For example, the line
\begin{lstlisting}
&MOVE ID='spin', ROTATION_ANGLE=45., X0=2., Y0=3., Z0=4., AXIS=1,0,0 /
\end{lstlisting}
causes an object to be rotated 45$^\circ$ about the direction vector ({\ct AXIS}) (1,0,0) emanating from the point $(x_0,y_0,z_0)$. You may also translate the object in the three coordinate directions using the parameters {\ct DX}, {\ct DY}, {\ct DZ}, each in meters.

Currently, this feature only applies to point and line devices, and in future shall be applied to non-rectangular immersed objects.



\chapter{Chemical Species}
\label{info:SPEC}

FDS was designed primarily to study fire phenomena, and much of the basic chemistry of combustion is handled with a minimum of user inputs. However, there are many applications in which you might want to simulate the movement of gases in the absence of fire, or additional chemical species might be added to a simulation that involves fire.  Gas species are defined with the input group
{\ct SPEC}.  This input group is used to define both {\em primitive} gas species and {\em lumped} species (mixtures of one or more primitive {\ct SPEC}).

There are different roles that a gas species might play in a simulation. A gas species might be explicitly tracked. In other words, a transport equation is solved for it. A gas species might be one component of a mixture of gases that are transported together. For example, FDS exploits the idea that the products of combustion from a fire mix and travel together; you only need to solve one transport equation for this ``lumped species.'' Or, a gas species might do both such as H$_2$O which could be both part of a lumped species for combustion products as well as an explicitly tracked species tracking H$_2$O from sprinkler droplet evaporation.

The default combustion model in FDS assumes that the reaction is mixing-controlled, and transport equations are solved for three species: the two lumped species of Products and Air (the default background) and the species Fuel (as defined on {\ct REAC}). There is no reason to solve individual (and costly) transport equations for the major reactants and products of combustion---Fuel, O$_2$, CO$_2$, H$_2$O, N$_2$, CO and soot---because they are all pre-tabulated functions of the three species. More detail on combustion is given in Chapter~\ref{chap:combustion}. For the moment, just realize that you need not, {\em and should not}, explicitly list the reactants and products of combustion using {\ct SPEC} lines if all you want is to model a fire involving a hydrocarbon fuel.



\section{Specifying Primitive Species}
\label{info:primitive}

The {\ct SPEC} namelist group is used to define a gas species in FDS. Once defined the species can be tracked as a single species (i.e., a primitive species) and/or the species can be used as part of one or more lumped species, also defined with {\ct SPEC}.  It is possible for a species to be both part of a lumped species and tracked separately. Often an extra gas introduced into a calculation is the same as a product of combustion, like water vapor from a sprinkler or carbon dioxide from an extinguisher. These gases are tracked separately. Thus, water vapor generated by the combustion is tracked via the {\ct PRODUCTS} lumped species variable and water vapor generated by evaporating sprinkler droplets is tracked via its own transport equation.

If a species is only to be used as part of one or more lumped species, {\ct LUMPED\_COMPONENT\_ONLY=.TRUE.} must be added to the {\ct SPEC} line.  This tells FDS not to allocate space for the species in the array of tracked gases. If a species is to be used as the background species, the parameter {\ct BACKGROUND=.TRUE.} should be set on the {\ct SPEC} line. A species with {\ct LUMPED\_COMPONENT\_ONLY=.TRUE.} cannot be used as an individual species, and it cannot be used as the background species.  However, a primitive species with {\ct BACKGROUND=.TRUE.} can also be used as part of a lumped species definition.  Note that the default background species is {\ct AIR} which is defined as a lumped species consisting of N$_2$, O$_2$, CO$_2$, and H$_2$O.  If no background species is defined in the input file, then FDS will create the background species of {\ct AIR} by internally creating the input lines shown in Example 2 in Section~\ref{info:lumped}.

Note that while you can define as many species using {\ct SPEC} as you wish in an input file, any namelist input tied to a list of species, such as any {\ct SPEC\_ID} input or {\ct MASS\_FRACTION} input, is limited to using no more than 20 species.

\subsection{Basics}
\label{info:SPEC_Basics}
\label{gas_filling}

Each {\ct SPEC} line should include at the very least the name of the species via a character string, {\ct ID}. Once the extra species has been declared, you introduce it at surfaces via the parameters {\ct MASS\_FRACTION(:)} or {\ct MASS\_FLUX(:)} along with the character array {\ct SPEC\_ID(:)}. A very simple example of how a gas---in this case hydrogen---can be introduced into the simulation is given by the simple input file called {\ct gas\_filling.fds}. The relevant lines are as follows:
\begin{lstlisting}
&SPEC ID='HYDROGEN' /
&SURF ID='LEAK', SPEC_ID(1)='HYDROGEN', MASS_FLUX(1)=0.01667, RAMP_MF(1)='leak_ramp' /
&RAMP ID='leak_ramp', T=  0., F=0.0 /
&RAMP ID='leak_ramp', T=  1., F=1.0 /
&RAMP ID='leak_ramp', T=180., F=1.0 /
&RAMP ID='leak_ramp', T=181., F=0.0 /
&VENT XB=-0.6,0.4,-0.6,0.4,0.0,0.0, SURF_ID='LEAK', COLOR='RED' /
&DUMP MASS_FILE=.TRUE. /
\end{lstlisting}
The hydrogen is injected through a 1~m by 1~m vent at a rate of 0.01667~\si{kg/(m$^2$.s)} and shut off after 3~min. The total mass of hydrogen at that point ought to be 3~kg (see Fig.~\ref{gas_filling_fig}). Notice that no properties were needed for the {\ct HYDROGEN} because it is a species whose properties are included in Table~\ref{tab:gasspecies}. The background species in this case is assumed to be air. The mass flow rate of the hydrogen is controlled via the ramping parameter {\ct RAMP\_MF(1)}. The parameter {\ct MASS\_FILE=.TRUE.} instructs FDS to produce an output file that contains a time history of the hydrogen mass.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=3.1in]{SCRIPT_FIGURES/gas_filling_mass}
\end{center}
\caption[Results of the {\ct gas\_filling} test case]{Hydrogen mass vs.~time for {\ct gas\_filling} test case.}
\label{gas_filling_fig}
\end{figure}

\subsubsection{Initial Conditions}

If the initial mass fraction of the gas is something other than zero, then the parameter {\ct MASS\_FRACTION\_0} is used to specify it. For example, if you want the initial concentration in the domain to be 90\% background (air) diluted with 10\% argon, use

\begin{lstlisting}
&SPEC ID='ARGON', MASS_FRACTION_0=0.1 /
\end{lstlisting}

\subsubsection{Specifying Humidity}
\label{info:humidity}

If you are using the default background lumped species {\ct AIR}, then you can specify {\ct HUMIDITY} on {\ct MISC} to set the ambient mass fraction of water vapor. {\ct HUMIDITY} is the relative humidity of water vapor in units of \%. It is 40 \% by default.

If you are defining the primitive species of {\ct WATER VAPOR}, then {\ct MASS\_FRACTION\_0} is independent of {\ct HUMIDITY}.  That is setting {\ct MASS\_FRACTION\_0} for the species {\ct WATER VAPOR} will not change the ambient humidity, it will add additional water vapor.

\subsection{Pre-Defined Gas and Liquid Properties}
\label{gas_species_props}

Gases and liquids whose properties are tabulated within FDS are listed in Table~\ref{tab:gasspecies}. The physical properties of these species are known and do not need to be specified. When using one of these gases you need only specify the correct {\ct ID} and provide, if needed, the initial mass fraction. FDS will then use precompiled data to compute the various thermophysical properties from 0 K to 5000 K.

\begin{longtable}{@{\extracolsep{\fill}}|l|c|c|c|c|c|l|}
\caption[Pre-defined gas and liquid species]{Pre-defined gas and liquid species~\cite{Reid:1}}
\label{tab:gasspecies}\\
\hline
Species &   Mol.~Wt.            & Chemical         & $\sigma$ & $\epsilon/k$   & Liquid   & RadCal                     \\
        &   (g/mol)             & Formula          & (\AA)    & (K)            &          & Surrogate                  \\
\hline \hline
\endfirsthead
\caption[]{Optional gas and liquid species (continued).}\\
\hline
Species &   Mol.~Wt.            & Formula          & $\sigma$ & $\epsilon/k$   & Liquid   & RadCal                     \\
        &   (g/mol)             &                  & (\AA)    & (K)            &          & Surrogate                  \\
\hline \hline
\endhead
{\ct ACETONE}            & 58.07914   & C$_3$H$_6$O      & 4.6      & 560.2    &  Y       &  {\ct MMA}                 \\ \hline
{\ct ACETYLENE}          & 26.037280  & C$_2$H$_2$       & 4.033    & 231.8    &          &  {\ct PROPYLENE}           \\ \hline
{\ct ACROLEIN}           & 56.063260  & C$_3$H$_4$O      & 4.549    & 576.7    &  Y       &  {\ct MMA}                 \\ \hline
{\ct AMMONIA}            & 17.03052  & NH$_3$            & 2.9      & 558.3    &  Y       &                            \\ \hline
{\ct ARGON}              & 39.948000  & Ar               & 3.42     & 124.0    &  Y       &                            \\ \hline
{\ct BENZENE}            & 78.11184   & C$_6$H$_6$       & 5.349    & 412.3    &  Y       &  {\ct TOLUENE}             \\ \hline
{\ct BUTANE}             & 58.122200  & C$_4$H$_{10}$    & 4.687    & 531.4    &  Y       &  {\ct PROPANE}             \\ \hline
{\ct CARBON}             & 12.0107    & C                & 2.94     & 74.8     &          &                            \\ \hline
{\ct CARBON DIOXIDE}     & 44.009500  & CO$_2$           & 3.941    & 195.2    &          &  {\ct CARBON DIOXIDE}      \\ \hline
{\ct CARBON MONOXIDE}    & 28.010100  & CO               & 3.690    & 91.7     &  Y       &  {\ct CARBON MONOXIDE}     \\ \hline
{\ct CHLORINE}           & 70.906     & Cl$_2$           & 4.217    & 316.0    &  Y       &                            \\ \hline
{\ct DODECANE}           & 170.33484  & C$_{12}$H$_{26}$     & 4.701    & 205.78   &  Y       &  {\ct N-HEPTANE}           \\ \hline
{\ct ETHANE}             & 30.069040  & C$_2$H$_6$       & 4.443    & 215.7    &  Y       &  {\ct ETHANE}              \\ \hline
{\ct ETHANOL}            & 46.068440  & C$_2$H$_5$OH     & 4.530    & 362.6    &  Y       &  {\ct METHANOL}            \\ \hline
{\ct ETHYLENE}           & 28.053160  & C$_2$H$_4$       & 4.163    & 224.7    &  Y       &  {\ct ETHYLENE}            \\ \hline
{\ct FORMALDEHYDE}       & 30.025980  & CH$_2$O          & 3.626    & 481.8    &  Y       &  {\ct METHANOL}            \\ \hline
{\ct HELIUM}             & 4.002602   & He               & 2.551    & 10.22    &  Y       &                            \\ \hline
{\ct HYDROGEN}           & 2.015880   & H$_2$            & 2.827    & 59.7     &  Y       &                            \\ \hline
{\ct HYDROGEN ATOM}      & 1.007940   & H                & 2.31     & 123.6    &          &                            \\ \hline
{\ct HYDROGEN BROMIDE}   & 80.911940  & HBr              & 3.353    & 449.0    &  Y       &                            \\ \hline
{\ct HYDROGEN CHLORIDE}  & 36.460940  & HCl              & 3.339    & 344.7    &  Y       &                            \\ \hline
{\ct HYDROGEN CYANIDE}   & 27.025340  & HCN              & 3.63     & 569.1    &  Y       &                            \\ \hline
{\ct HYDROGEN FLUORIDE}  & 20.006343  & HF               & 3.148    & 330.0    &  Y       &                            \\ \hline
{\ct HYDROGEN PEROXIDE}  & 34.014680  & H$_2$O$_2$       & 3.02     & 106.5    &  Y       &                            \\ \hline
{\ct HYDROGEN SULFIDE}   & 34.08088   & H$_2$S           & 3.623    & 301.1    &  Y       &                            \\ \hline
{\ct HYDROPEROXY RADICAL}& 33.006740  & HO$_2$           & 3.02     & 106.5    &          &                            \\ \hline
{\ct HYDROXYL RADICAL}   & 17.007340  & OH               & 2.66     & 92.1     &          &                            \\ \hline
{\ct ISOPROPANOL}        & 60.095020  & C$_3$H$_7$OH     & 4.549    & 576.7    &  Y       &  {\ct METHANOL}            \\ \hline
{\ct LJ AIR}             & 28.854760  &                  & 3.711    & 78.6     &          &                            \\ \hline
{\ct METHANE}            & 16.042460  & CH$_4$           & 3.758    & 148.6    &  Y       &  {\ct METHANE}             \\ \hline
{\ct METHANOL}           & 32.041860  & CH$_3$OH         & 3.626    & 481.8    &  Y       &  {\ct METHANOL}            \\ \hline
{\ct N-DECANE}           & 142.281680 & C$_{10}$H$_{22}$ & 5.233    & 226.46   &  Y       &  {\ct N-HEPTANE}           \\ \hline
{\ct N-HEPTANE}          & 100.201940 & C$_7$H$_{16}$    & 4.701    & 205.75   &  Y       &  {\ct N-HEPTANE}           \\ \hline
{\ct N-HEXANE}           & 86.175360  & C$_6$H$_{12}$    & 5.949    & 399.3    &  Y       &  {\ct N-HEPTANE}           \\ \hline
{\ct N-OCTANE}           & 114.228520 & C$_8$H$_{18}$    & 4.892    & 231.16   &  Y       &  {\ct N-HEPTANE}           \\ \hline
{\ct NITRIC OXIDE}       & 30.006100  & NO               & 3.492    & 116.7    &  Y       &                            \\ \hline
{\ct NITROGEN}           & 28.013400  & N$_2$            & 3.798    & 71.4     &  Y       &                            \\ \hline
{\ct NITROGEN ATOM}      & 14.006700  & N                & 2.66     & 92.1     &          &                            \\ \hline
{\ct NITROGEN DIOXIDE}   & 46.05500   & NO$_2$           & 3.992    & 204.88   &  Y       &                            \\ \hline
{\ct NITROUS OXIDE}      & 44.012800  & N$_2$O           & 3.828    & 232.4    &  Y       &                            \\ \hline
{\ct OXYGEN}             & 31.998800  & O$_2$            & 3.467    & 106.7    &  Y       &                            \\ \hline
{\ct OXYGEN ATOM}        & 15.999400  & O                & 2.66     & 92.1     &          &                            \\ \hline
{\ct PROPANE}            & 44.095620  & C$_3$H$_8$       & 5.118    & 237.1    &  Y       &  {\ct PROPANE}             \\ \hline
{\ct PROPYLENE}          & 42.079740  & C$_3$H$_6$       & 4.678    & 298.9    &  Y       &  {\ct PROPYLENE}           \\ \hline
{\ct SOOT}               & 10.910420  & C$_{0.9}$H$_{0.1}$ & 3.798    & 71.4     &          &  {\ct SOOT}                \\ \hline
{\ct SULFUR DIOXIDE}     & 64.063800  & SO$_2$           & 4.112    & 335.4    &  Y       &                            \\ \hline
{\ct SULFUR HEXAFLUORIDE}& 146.055419 & SF$_6$           & 5.128    & 146.0    &          &                            \\ \hline
{\ct TOLUENE}            & 92.138420  & C$_6$H$_5$CH$_3$ & 5.698    & 480.0    &  Y       &  {\ct TOLUENE}             \\ \hline
{\ct WATER VAPOR}        & 18.015280  & H$_2$O           & 2.641    & 809.1    &  Y       &  {\ct WATER VAPOR}         \\ \hline
{\ct XENON}           & 131.293  & Xe               & 4.047   & 231.0    &  Y       &                            \\ \hline
\end{longtable}


\subsection{User-Defined Gas and Liquid Properties}
\label{user_defined_gas_species_props}

If the gas species is not included in Table~\ref{tab:gasspecies}, then you must specify its thermo-physical properties.  By using the inputs discussed below, you can also override the default properties for a pre-defined gas species.  For a gas species not included in Table~\ref{tab:gasspecies}, its molecular weight, {\ct MW}, should be specified on the {\ct SPEC} line in units of g/mol, otherwise the molecular weight of nitrogen will be used.  If the species is participating in a reaction, then the {\ct ENTHALPY\_OF\_FORMATION} in units of kJ/mol must also be specified. Additional discussion on the enthalpy of formation can be found in Chapter~\ref{chap:combustion}.  The remaining thermo-physical properties of conductivity, diffusivity, enthalpy, viscosity, absorptivity (thermal radiation), and liquid properties are discussed below. Most properties can be defined as a constant value or as a temperature dependent look-up table using a {\ct RAMP}. For the latter, if the temperature in a gas cell is above or below the endpoints of the {\ct RAMP}, the endpoint value will be used. FDS will not extrapolate beyond the ends of the {\ct RAMP}.

Note that most of the parameters listed below, with the exception of the chemical {\ct FORMULA} or molecular weight, {\ct MW}, are not necessary for large eddy simulations (LES). If any of these properties listed below are not provided, FDS typically defaults to the properties of nitrogen, the dominant species in typical fire or combustion scenarios.

\subsubsection{Specifying a Chemical Formula}
\label{info:FORMULA}

If you want FDS to compute the molecular weight of the gas species, you can input a {\ct FORMULA} rather than the molecular weight, {\ct MW}. This will also be used as the label for the gas species by Smokeview.  {\ct FORMULA} is a character string consisting of elements followed by their atom count. Subgroups bracketed by parentheses can also be given.  The element name is given by its standard, case-sensitive, IUPAC\footnote{International Union of Pure and Applied Chemistry} abbreviation (e.g., C for carbon, He for helium). The following are all equivalent:
\begin{lstlisting}
&SPEC ID='ETHYLENE GLYCOL', FORMULA='C2H6O2'/
&SPEC ID='ETHYLENE GLYCOL', FORMULA='OHC2H4OH'/
&SPEC ID='ETHYLENE GLYCOL', FORMULA='C2H4(OH)2'/
\end{lstlisting}

\subsubsection{Conductivity}

Conductivity can be specified in one of three ways: it can be defined as a constant using {\ct CONDUCTIVITY} (\si{W/(m.K)}), it can be defined as a temperature vs. specific heat ramp  using {\ct RAMP\_K}, or it can be computed by FDS using {\ct MW}, {\ct PR\_GAS} on {\ct SPEC} (default value is {\ct PR} on {\ct MISC}), and the Lennard-Jones potential parameters $\sigma$ ({\ct SIGMALJ}) and $\epsilon/k$ ({\ct EPSILONKLJ}).  If no inputs are specified, FDS will compute the conductivity using the {\ct MW} and the Lennard-Jones parameters for nitrogen.

\subsubsection{Diffusivity}

Diffusivity is assumed to be the binary diffusion coefficient between the given species and the background species. Diffusivty can be specified in one of three ways:  it can be defined as a constant using {\ct DIFFUSIVITY} (m$^2$/s), it can be defined as a temperature vs. diffusivity ramp  using {\ct RAMP\_D}, or it can be computed by FDS using {\ct MW} and the Lennard-Jones potential parameters $\sigma$ ({\ct SIGMALJ}) and $\epsilon/k$ ({\ct EPSILONKLJ}).  If no inputs are specified, FDS will compute the diffusivity using the {\ct MW} and the Lennard-Jones parameters for nitrogen.

\subsubsection{Enthalpy}
\label{info:Enthalpy}

The enthalpy of the gas mixture is given by the following formula:
\be
   h(T) = h(T_{\rm ref}) + \int_{T_{\rm ref}}^T c_p(T') \, \d T'
\ee
where $c_p$ is the {\ct SPECIFIC\_HEAT} (\si{kJ/(kg.K)}) with optional temperature dependence using {\ct RAMP\_CP}.  The (optional) {\ct REFERENCE\_TEMPERATURE}, $T_{\rm ref}$ ($^\circ$C), is the temperature that corresponds to the \linebreak[4] {\ct REFERENCE\_ENTHALPY}, $h(T_{\rm ref})$ (kJ/kg).  The default value of the  {\ct REFERENCE\_TEMPERATURE} is 25~$^\circ$C.  If {\ct SPECIFIC\_HEAT} is specified and the {\ct REFERENCE\_ENTHALPY} is not, the {\ct REFERENCE\_ENTHALPY} will be set to $h(T_{\rm ref})=c_p T_{\rm ref}$.

If no inputs for enthalpy are provided, then the specific heat of the gas will be calculated from its molecular weight using the relation:
\be
   c_{p,\alpha} = \frac{\gamma}{\gamma-1} \frac{\R}{W_\alpha}
\ee
The ratio of specific heats, {\ct GAMMA}, is 1.4 by default and can be changed on the {\ct MISC} line. If you want all the gas specific heats to follow this relation, set {\ct CONSTANT\_SPECIFIC\_HEAT\_RATIO=.TRUE.} on the {\ct MISC} line (note: this option also requires {\ct STRATIFICATION=.FALSE.} on the {\ct WIND} line and {\ct EXTINCTION\_MODEL = 'EXTINCTION 1'} or {\ct SUPPRESSION=.FALSE.} on the {\ct COMB} line).  In this case the {\ct REFERENCE\_ENTHALPY} will be assumed to be 0 kJ/kg at a {\ct REFERENCE\_TEMPERATURE} of 0 K. For high molecular weight species, use of the default gamma will result in very low values of the specific heat which can cause issues with the default extinction model. In this case it is recommended that enthalpy are provided. If the FDS is determining enthalpies using this relation, then it is recommended that you check the {\ct CHID.out} and verify that reasonable specific heat values have been created.

The reference enthalpy can also be determined by defining the {\ct ENTHALPY\_OF\_FORMATION} on the {\ct SPEC} line with a reference temperature for all species given by {\ct H\_F\_REFERENCE\_TEMPERATURE} on the {\ct MISC} line (default is 25~$^\circ$C). Note that {\ct ENTHALPY\_OF\_FORMATION} will override any value given for {\ct REFERENCE\_ENTHALPY}.

\subsubsection{Viscosity}

The dynamic viscosity of the gas species can be specified in one of three ways:  it can be defined as a constant using {\ct VISCOSITY}, it can be defined as a temperature vs. viscosity ramp  using {\ct RAMP\_MU}, or it can be computed  using the Lennard-Jones potential parameters $\sigma$ ({\ct SIGMALJ}) and $\epsilon/k$ ({\ct EPSILONKLJ}).  If no viscosity inputs are provided, FDS will use the Lennard-Jones values for nitrogen.

\subsubsection{Radiative Properties}
\label{info:radiative_spec_props}

Species that can absorb and emit thermal radiation are defined via the parameter {\ct RADCAL\_ID} on the {\ct SPEC} line.  Some of the predefined species have this parameter already defined as shown in Table~\ref{tab:gasspecies}.  There are, however, many other species which are absorbing.  For absorbing species not listed in Table~\ref{tab:gasspecies}, {\ct RADCAL\_ID} can be used to identify a RadCal~\cite{RadCal} species to serve as a surrogate. For example:
\begin{lstlisting}
&SPEC ID='ETHANOL', RADCAL_ID='METHANOL' /
\end{lstlisting}
would use the RadCal absorptivities for {\ct METHANOL} when computing the absorptivity of {\ct ETHANOL}. For absorbing species not present in RadCal, it is recommended to choose a RadCal surrogate with similar molecular functional groups and molecular mass. The infrared spectrum is greatly affected by the species molecular functional groups.

Species molecular mass also affects the spectrum: a heavier species of a given molecular functional group tends to absorb and emit more infrared radiation than a lighter species of the same functional group.  For simple chemistry, if the fuel is not present in Table~\ref{tab:gasspecies} and no {\ct FUEL\_RADCAL\_ID} is provided on the {\ct REAC} line, then the absorption properties of methane will be used.

\subsubsection{Gibbs Energy}

If a reverse chemical reaction is specified using {\ct REVERSE=.TRUE.} on a {\ct REAC} input, FDS will use the forward reaction kinetics along with the equilibrium values of the reaction to determine the value of the rate constant for the reverse reaction.  The equilibrium constant is determined from the Gibbs free energy.  The Gibbs free energy (kJ/mol) as a function of temperature for a species can be specified with {\ct RAMP\_G\_F} on the {\ct SPEC} line.

\subsubsection{Liquids}

The only instance where detailed liquid properties are needed is when defining a liquid droplet for a species not listed in Table~\ref{tab:gasspecies}. The necessary properties are described in Section~\ref{thermal_part_props}.




\subsection{Air}

There are two predefined species for air in FDS. The first predefined species is the default background species of {\ct AIR}. This is a lumped species consisting of oxygen, nitrogen, carbon dioxide, and water vapor whose mass fractions are controlled by the {\ct Y\_CO2\_INFTY}, {\ct Y\_O2\_INFTY}, and {\ct HUMIDITY} inputs. This lumped species is automatically defined by FDS if no other {\ct SPEC} input is defined as the {\ct BACKGROUND}. Note that {\ct ID='AIR'} cannot be used on a {\ct SPEC} input unless that input or some other {\ct SPEC} input is defined as the {\ct BACKGROUND}. The second predefined species is the primitive species of {\ct LJ AIR}. This is an effective gas species whose molecular weight and enthalpy are defined based on the {\ct Y\_CO2\_INFTY} and {\ct Y\_O2\_INFTY} inputs, and whose other thermophysical properties use the Lennard-Jones parameters for air. For simulations without combustion, using {\ct LJ AIR} as the {\ct BACKGROUND} species will slightly reduce the computational cost.


\subsection{Two Gas Species with the Same Properties}
\label{info:SPEC_advanced}

In general only one species for a given {\ct ID} can be defined; however, you may wish to model multiple inlet streams of a species and be able to identify how well the streams are mixing.  This can be done by defining a new species with a single component.  For example, the lines:
\begin{lstlisting}
&SPEC ID='CARBON DIOXIDE', LUMPED_COMPONENT_ONLY=.TRUE./
&SPEC ID='CO2 1',SPEC_ID='CARBON DIOXIDE'/
&SPEC ID='CO2 2',SPEC_ID='CARBON DIOXIDE'/
&DEVC XYZ=..., QUANTITY='MASS FRACTION', SPEC_ID='CO2 1', ID='Device 1'/
&DEVC XYZ=..., QUANTITY='MASS FRACTION', SPEC_ID='CO2 2', ID='Device 2'/
\end{lstlisting}
define two duplicate species, both of which are {\ct CARBON DIOXIDE}.  Both will use the built in property data for CO$_2$ (note specifying one or more properties for a duplicate species will override the default properties).  The {\ct ID} for each duplicate species can then be used in the remainder of the input file.  In this example, the {\ct LUMPED\_COMPONENT\_ONLY} was given so that FDS only tracks {\ct CO2 1} and {\ct CO2 2} and not {\ct CARBON DIOXIDE}.  Note that the {\ct ID} you provide for a duplicate species cannot match the {\ct ID} of any other primitive or lumped {\ct SPEC} input.  Also note that this feature can only be used to duplicate a predefined species (i.e. a species listed in Table~\ref{tab:gasspecies}).

In the above example, the two {\ct DEVC} lines refer to the {\ct ID}s of the duplicate species.  If instead the primitive species {\ct ID} was used, then the output would sum the mass fractions over all species containing that primitive species.  For example, if the output quantities in the example above are changed as shown below, then {\ct Device 1} would just output the mass fraction of {\ct CO2 1} and {\ct Device 2} would output the sum of both.
\begin{lstlisting}
&DEVC XYZ=..., QUANTITY='MASS FRACTION', SPEC_ID='CO2 1', ID='Device 1'/
&DEVC XYZ=..., QUANTITY='MASS FRACTION', SPEC_ID='CARBON DIOXIDE', ID='Device 2'/
\end{lstlisting}
Another application of this would be if you wanted to track the water that evaporated from sprinklers, separately from the water
that resulted from combustion.  The following inputs would allow you to do that:
\begin{lstlisting}
&REAC FUEL='PROPANE', ... /
&SPEC ID='WATER VAPOR SPK', SPEC_ID='WATER VAPOR' /
&PART ID='Sprinkler Droplets',SPEC_ID='WATER VAPOR SPK'/
&DEVC XYZ=..., QUANTITY='MASS FRACTION', SPEC_ID='WATER VAPOR SPK', ID='Spr H2O'/
&DEVC XYZ=..., QUANTITY='MASS FRACTION', SPEC_ID='WATER VAPOR', ID='All H2O'/
\end{lstlisting}
The gas species called {\ct WATER VAPOR SPK} has the same properties as {\ct WATER VAPOR}. The first device records only water that results from droplet evaporation, and the second device records water that originates from both sprinklers and combustion.

By default, duplicate species are considered to be a lumped species and not a primitive species.  That is, by default, a duplicate species cannot be used in a lumped species definition.  Setting {\ct PRIMITIVE=.TRUE.} will have FDS treat the duplicate species as a primitive species and allow it to be used in a lumped species definition.  Note that when this is done, one can no longer aggregate {\ct SPEC\_ID} based outputs over the original and the duplicate species as the aggregation is done on the basis of the primitive species names.  This is demonstrated in the example below.  The species {\ct O2} and {\ct O3} are duplicate species of {\ct OXYGEN}.  {\ct O3} is defined as a primitive species and {\ct O2} is considered only a lumped species.  The initial {\ct DEVC} outputs in order would be 0.3 (0.1 for {\ct OXYGEN} plus 0.2 for {\ct O2}), 0.2 (the {\ct O2} initial value), and 0.3 (the {\ct O3} initial value).  Note the {\ct OXYGEN} output is not 0.6 since the {\ct O3} is defined as a new primitive species.
\begin{lstlisting}
&SPEC ID='NITROGEN',BACKGROUND=.TRUE./
&SPEC ID='OXYGEN',MASS_FRACTION_0=0.1/
&SPEC ID='O2',SPEC_ID='OXYGEN',MASS_FRACTION_0=0.2/
&SPEC ID='O3',SPEC_ID='OXYGEN',MASS_FRACTION_0=0.3,PRIMITIVE=.TRUE./

&DEVC XYZ=0.5,0.5,0.5,QUANTITY='MASS FRACTION',SPEC_ID='OXYGEN'/
&DEVC XYZ=0.5,0.5,0.5,QUANTITY='MASS FRACTION',SPEC_ID='O2'/
&DEVC XYZ=0.5,0.5,0.5,QUANTITY='MASS FRACTION',SPEC_ID='O3'/
\end{lstlisting}

\section{Specifying Lumped Species (Mixtures of Primitive Species)}
\label{info:lumped}

The {\ct SPEC} namelist group also allows you to define species mixtures. The purpose of a species mixture is to reduce the number of species transport equations that are explicitly solved. For example, consider air. Air is composed of nitrogen, oxygen, water vapor, and carbon dioxide. If we define the four component species of air, we will have four total species. One of these, say nitrogen, can be set to be the background species, leaving three transport equations to solve. Alternatively, we can define a ``lumped species'' that represents the air mixture and save on CPU time because the three transport equations are no longer needed and the ``lumped'' air becomes the background species.

The following inputs define equivalent initial mixtures. But in the first example three species are explicitly tracked and in the second example only a background mixture is specified.  Note that this example represents the background species created by FDS when no background is explicitly defined in the input file.  It is also noted that any implicitly defined species (such as the nitrogen, oxygen, water vapor, and carbon dioxide for the air background species or the species in the lumped product species for simple chemistry, see ~\ref{info:simple_chemistry}), can be referenced by any of the outputs such as {\ct DEVC} or {\ct SLCF}.

\subsubsection{Example 1: All primitive species}

\begin{lstlisting}
&SPEC ID='NITROGEN', BACKGROUND=.TRUE. / Note: The background must be defined first.
&SPEC ID='OXYGEN',         MASS_FRACTION_0=0.23054 /
&SPEC ID='WATER VAPOR',    MASS_FRACTION_0=0.00626 /
&SPEC ID='CARBON DIOXIDE', MASS_FRACTION_0=0.00046 /
\end{lstlisting}

\subsubsection{Example 2: Defining a background species}

\begin{lstlisting}
&SPEC ID='NITROGEN',       LUMPED_COMPONENT_ONLY=.TRUE. /
&SPEC ID='OXYGEN',         LUMPED_COMPONENT_ONLY=.TRUE. /
&SPEC ID='WATER VAPOR',    LUMPED_COMPONENT_ONLY=.TRUE. /
&SPEC ID='CARBON DIOXIDE', LUMPED_COMPONENT_ONLY=.TRUE. /

&SPEC ID='AIR', BACKGROUND=.TRUE.,
      SPEC_ID(1)='NITROGEN',       MASS_FRACTION(1)=0.76274,
      SPEC_ID(2)='OXYGEN',         MASS_FRACTION(2)=0.23054,
      SPEC_ID(3)='WATER VAPOR',    MASS_FRACTION(3)=0.00626,
      SPEC_ID(4)='CARBON DIOXIDE', MASS_FRACTION(4)=0.00046 /
\end{lstlisting}
The logical parameter {\ct LUMPED\_COMPONENT\_ONLY} indicates that the species is only present as part of a lumped species. When {\ct .TRUE.}, FDS will not allocate space to track that species individually. The parameters to define a lumped species are:
\begin{description}
\item[{\ct BACKGROUND}] Denotes that this lumped species is to be used as the background species.
\item[{\ct ID}] Character string identifying the name of the species. You must provide this.  This cannot be the same as an {\ct ID} of another {\ct SPEC} input.
\item[{\ct SPEC\_ID}] Character array containing the names of the primitive species that make up the lumped species.
\item[{\ct MASS\_FRACTION}] The mass fractions of the components of the lumped species in the order listed by {\ct SPEC\_ID}.  FDS will normalize the values to 1. Alternatively, {\ct VOLUME\_FRACTION} can be specified. Do not use both on an {\ct SPEC} line.
\item[{\ct MASS\_FRACTION\_0}] The initial mass fractions of lumped species.
\end{description}
When defining a lumped species, either {\ct MASS\_FRACTION} or {\ct VOLUME\_FRACTION} must be used to define the component species. The addition of lumped species to FDS has changed the meaning of {\ct SPEC\_ID} on some FDS inputs.  For {\ct INIT},
{\ct MATL}, {\ct PART}, and {\ct SURF}, {\ct SPEC\_ID} refers to either a tracked primitive species or a lumped species.  For outputs and devices, {\ct DEVC}, that require a {\ct SPEC\_ID}, the {\ct SPEC\_ID} input can refer to either a tracked primitive species, a lumped species, or a lumped species component that is not tracked.  For {\ct REAC} see the discussion on specifying reactions in Chapter~\ref{info:REAC}.

\subsection{Combining Lumped and Primitive Species}

There are cases where you may wish to have a single primitive species be both part of a lumped species and also a separately tracked species.  For example, when using simple chemistry, Section~\ref{info:simple_chemistry}, FDS will include water vapor in the product species and in the air background species.  If you also wish to have sprinklers in the simulation, then you will need to track water vapor from the sprinklers separately from that in the air or products.  This is simply done by adding the line:

\begin{lstlisting}
&SPEC ID='WATER VAPOR'/
\end{lstlisting}
This will override the implicitly created water vapor species defined with {\ct LUMPED\_COMPONENT\_ONLY=.TRUE.} and cause FDS to track water vapor as a separate species.  Note that in this case if you requested an output for the mass fraction of {\ct WATER VAPOR} you would get the water vapor in the air and product lumped species as well as that which evaporated from sprinkler droplets.  If you wanted in this case (where water vapor is implicitly defined), to be able to track the water vapor from sprinklers separately you could follow the example in Section~\ref{info:SPEC_advanced} and define:

\begin{lstlisting}
&SPEC ID='SPRINKLER WATER VAPOR',SPEC_ID='WATER VAPOR'/
\end{lstlisting}
Using the species  {\ct SPRINKLER WATER VAPOR} for the sprinklers would allow you to track sprinkler generated water vapor separately.

\chapter{Combustion}

\label{chap:combustion}
\label{info:REAC}
\label{info:COMB}

A common source of confusion in FDS is the distinction between gas phase {\em combustion} and solid phase {\em pyrolysis}. The former refers to the reaction of fuel vapor and oxygen; the latter the generation of fuel vapor at a solid or liquid surface. Whereas there can be multiple solid or liquid combustibles in an FDS fire simulation, in the default simple chemistry, mixing-controlled combustion model there can only be one gaseous fuel. The reason is cost. It is expensive to solve transport equations for multiple gaseous fuels. Consequently, the burning rates of solids and liquids are automatically adjusted by FDS to account for the difference in the heats of combustion of the various combustibles. In effect, you specify a single gas phase reaction as a surrogate for all potential fuels.

Combustion can be modeled in two ways. By default, the reaction of fuel and oxygen is infinitely fast and controlled only by mixing, hence the label {\em mixing-controlled}. The alternative is that the reaction is {\em finite-rate}. The latter approach usually requires very fine grid resolution that is not practical for large-scale fire applications. This chapter describes both methods, with an emphasis on the more commonly used mixing-controlled model.

There are two groups of parameters that govern combustion. The first, called the {\ct COMB} namelist group, contains parameters that pertain to any and all reactions. Specific parameters about a particular reaction are specified using the {\ct REAC} namelist group. There can only be one {\ct COMB} line, but multiple {\ct REAC} lines if there are multiple reactions. If you are modeling a fire, you {\em must} specify the fuel and basic stoichiometry using a {\ct REAC} line. You need not specify a {\ct COMB} line unless you want to modify mainly numerical parameters.


\section{Single-Step, Mixing-Controlled Combustion}

This approach to combustion, referred to below as the ``simple chemistry'' combustion model, considers a single fuel species that is composed primarily of C, H, O, and N that reacts with oxygen in one mixing-controlled step to form H$_2$O, CO$_2$, soot, and CO. Information about the reaction is provided on the {\ct REAC} line. Starting with FDS~6, you {\em must} specify a {\ct REAC} line to model a fire. You are responsible for defining the basic fuel chemistry and the post-combustion yields of CO and soot. The default values are 0.

\subsection{Simple Chemistry Parameters}
\label{info:simple_chemistry}

For the simple chemistry model, each reaction is assumed to be of the form:
\be \mathrm{C_xH_yO_zN_v} + \nu_{\OTWO} \; \mathrm{O_2} \rightarrow
    \nu_{\COTWO} \; \mathrm{CO_2} + \nu_{\HTWOO} \; \mathrm{H_2O} +
    \nu_{\CO}   \; \mathrm{CO}   + \nu_{\rm S} \; \mathrm{Soot} + \nu_{\NTWO} \; \mathrm{N_2} \ee
You need only specify the chemical formula of the fuel along with the yields of CO and soot, and the volume fraction of hydrogen in the soot, $X_\Hy$. FDS will use that information and calculate the stoichiometric coefficients automatically as follows:
\begin{eqnarray*}
\nu_{\OTWO}    &=& \nu_{\COTWO} + \frac{\nu_{\CO}}{2} + \frac{\nu_{\HTWOO}}{2} - \frac{\hbox{z}}{2}   \\
\nu_{\COTWO}   &=& \hbox{x} - \nu_{\CO} - (1-X_\Hy) \, \nu_{\rm S} \\
\nu_{\HTWOO}   &=& \frac{\hbox{y}}{2} - \frac{X_\Hy}{2} \, \nu_{\rm S} \\
\nu_{\CO}      &=& \frac{W_{\rm F}}{W_{\CO}} \, y_{\CO}  \\
\nu_{\rm s}          &=& \frac{W_{\rm F}}{W_{\rm S}} \, y_{\rm S}  \\
\nu_{\NTWO}    &=& \frac{\rm v}{2}  \\
W_{\rm s}            &=& X_\Hy \, W_\Hy + (1-X_\Hy) \, W_\C
\end{eqnarray*}
The following parameters may be prescribed on the {\ct REAC} line when using the simple chemistry model.
Note that the various {\ct YIELD}s are for well-ventilated, post-flame conditions. There are options to
predict various species yields in under-ventilated fire scenarios, but these special models still require
the post-flame yields for CO, soot and any other species listed below.
\begin{description}
\item[{\ct FUEL}] (Required) A character string that identifies fuel species for the reaction. When using simple chemistry, specifying {\ct FUEL} will
cause FDS to use the built-in thermophysical properties for that species when computing quantities such as specific heat or viscosity.
Table~\ref{tab:gasspecies} provides a listing of the available species.
If the {\ct FUEL} is in the table, then FDS will use the built-in formula to obtain the values of C, H, O, and N.
If not listed in Table~\ref{tab:gasspecies}, FDS uses the gas thermophysical properties of {\ct ETHYLENE} along with the molecular weight given by the {\ct FORLMULA} or the values of C, H, O, and N.  Either way, FDS will implicitly create a {\ct SPEC} input for {\ct FUEL}.  This allows {\ct FUEL} to be used as a {\ct SPEC\_ID} input elsewhere (for example as an initial condition or an output quantity).  If you define {\ct FUEL} yourself as a {\ct SPEC}, any properties you specify will override the default values.
\item[{\ct FORMULA}] A character string that identities the chemical formula of the fuel species for the reaction.
This input only has meaning when simple chemistry is being used and the formula can only contain C, H, O, or N.
Specifying a formula means the individual inputs of C, H, O, and N do not need to be specified. See ~\ref{gas_species_props} for a description on how to input a {\ct FORMULA}.
\item[{\ct ID}] A character string that identifies the reaction. Normally, this label is not used by FDS, but it is useful to
label the {\ct REAC} line if more than one reactions are specified.
\item[{\ct C, H, O, N}] The fuel chemical formula. All numbers are positive.  One of either {\ct C} or {\ct H} must be specified.
This input is not needed if {\ct FORMULA} is specified or if the {\ct FUEL} is in Table~\ref{tab:gasspecies}.
\item[{\ct CO\_YIELD}] The fraction of fuel mass converted into carbon monoxide, $y_{\CO}$. Note that this parameter is only appropriate when the
simple chemistry model is applied. (Default 0.)
\item[{\ct SOOT\_YIELD}] The fraction of fuel mass converted into smoke particulate, $y_{\rm s}$.
Note that this parameter is only appropriate when the simple chemistry model is applied.  (Default 0.)
\item[{\ct SOOT\_H\_FRACTION}] The fraction of the atoms in the soot that are hydrogen.  The default value is 0.1, equivalent to the input {\ct FORMULA='C0.9H0.1'} (Section~\ref{info:FORMULA}). Note that this parameter is only appropriate when the simple chemistry model is applied.
\item[{\ct FUEL\_RADCAL\_ID}] RadCal species to be used for the fuel.  The default is the default RadCal species for the fuel species or {\ct 'METHANE'} if there is no species default. See Section~\ref{info:RadCal_fuelspecies} for details.
\end{description}
The ambient mass fractions for the constituents of air are specified on {\ct MISC} using the inputs:
\begin{description}
\item[{\ct Y\_O2\_INFTY}] Ambient mass fraction of oxygen (Default for dry air is 0.232378)
\item[{\ct Y\_CO2\_INFTY}] Ambient mass fraction of carbon dioxide (Default for dry air is 0.000595)
\item[{\ct HUMIDITY}] Relative humidity of the background air species, in units of \%. (Default 40~\%).
\end{description}
A few sample {\ct REAC} lines are given here.
\begin{lstlisting}
&REAC FUEL = 'METHANE' /
\end{lstlisting}
In this case, there is no need for a {\ct FORMULA} or atom count because the {\ct FUEL} is listed in Table~\ref{tab:gasspecies}. It is assumed that the soot and CO yields are zero.  FDS will compute the yields of product species and the heat of combustion based upon predefined values.
\begin{lstlisting}
&REAC FUEL               = 'PROPANE'
      SOOT_YIELD         = 0.01
      CO_YIELD           = 0.02
      HEAT_OF_COMBUSTION = 46460. /
\end{lstlisting}
In this case, the fuel species is again predefined.  However, here the heat of combustion is specified explicitly rather than calculated. Additionally, minor species yields have been specified with the soot yield specified as 0.01 and the CO yield specified as 0.02.
See Section~\ref{info:heat_of_combustion} for more details on the heat of combustion.
\begin{lstlisting}
&REAC FUEL               = 'MY FUEL'
      FORMULA            = 'C3H8O3N4'
      HEAT_OF_COMBUSTION = 46124. /
\end{lstlisting}
In this case, the fuel is not predefined.  Therefore, either the {\ct FORMULA} or the atom counts must be defined.  This input defined the {\ct FORMULA}. In this case, the heat of combustion is known and specified; however, if it weren't FDS would compute it using {\ct EPUMO2} and the fuel chemistry. Note that simple chemistry can also be used for cases where the fuel is a lumped species so long as the defining primitive species contain only C, H, N, and O atoms. An example can be found in Section \ref{info:Complex_Fuel}.

When simple chemistry is being used, FDS will automatically create three lumped species: {\ct AIR}, {\ct FUEL}, and {\ct PRODUCTS}.  The actual name of the fuel species will be the name given on the {\ct REAC} line (for example {\ct MY FUEL} in the last sample above). FDS creates these lumped species in the same manner as you would in an input file.  FDS first defines the primitive species and then defines the lumped species. In essence FDS internally creates input lines like those shown in Example 2 of Section~\ref{info:lumped}. This means when doing simple chemistry, that even though you did not explicitly define oxygen in the input file, you can request an output for oxygen since it was implicitly defined by FDS.

\subsection{Heat of Combustion}
\label{info:heat_of_combustion}

The energy release per unit volume (kJ/m$^3$) from a gas phase chemical reaction (or system of reactions) is found by taking the sum of the net change in mass for each species in a given time step multiplied by the respective species' enthalpy of formation (kJ/kg). In this formulation, the enthalpy of formation for all participating species needs to be specified. If a reaction (simple chemistry or user-defined) contains only species defined in Table~\ref{tab:gasspecies}, then all of the enthalpies of formation are known. These values can be found in the FDS source code in data.f90. For reactions with species that are not included in Table~\ref{tab:gasspecies}, there are several options to ensure that all of the enthalpies of formation are specified.

\subsubsection{Option 1: Specify Enthalpy of Formation}

You can specify unknown enthalpies on the {\ct SPEC} line in units of kJ/mol:
\begin{lstlisting}
&SPEC ID = 'GLUCOSE', FORMULA = 'C62H12O6', ENTHALPY_OF_FORMATION=-1.297E3 /
\end{lstlisting}

\subsubsection{Option 2: Specify Heat of Combustion}

For a given reaction, if the only species missing an enthalpy of formation is the fuel, the missing value can be found if the heat of combustion is specified on {\ct REAC}. Section~\ref{info:Complex_Fuel} provides an example for which the fuel, polyvinyl chloride, has an unspecified enthalpy of formation but a specified heat of combustion on the {\ct REAC} line.

\subsubsection{Option 3: Use of EPUMO2 (Simple Chemistry)}

If the enthalpy of formation of the fuel and heat of combustion are not specified, for simple chemistry cases only, the heat of combustion is assumed to be
\begin{equation}
\Delta h \approx \frac{\nu_{\OTWO} \, W_{\OTWO} } { \nu_{\rm F} \, W_{\rm F} } \; \; \hbox{\ct EPUMO2}  \quad \quad \hbox{kJ/kg}
\label{EPUMO2}
\end{equation}
The quantity {\ct EPUMO2} (kJ/kg) is the amount of energy released per unit mass of oxygen consumed.
Its default is 13,100~kJ/kg. Typically, a chemical reaction is balanced by setting
the stoichiometric coefficient of the fuel $\nu_{\rm F}$ to 1. In FDS, the stoichiometric coefficients of
the chemical reaction are normalized by the  stoichiometric coefficient of the fuel, effectively setting $\nu_{\rm F}$ to 1.
Note that if both {\ct EPUMO2} and {\ct HEAT\_OF\_COMBUSTION} are specified that FDS will ignore
the value for {\ct EPUMO2}. From the {\ct HEAT\_OF\_COMBUSTION}, FDS solves for the enthalpy of formation of the fuel.

If heats of reaction have been specified on the
{\ct MATL} lines and
the heats of combustion of the materials differ from that specified by
the governing gas phase reaction, then add a
{\ct HEAT\_OF\_COMBUSTION} (kJ/kg) to the {\ct MATL} line.
With the simple chemistry combustion
model, it is assumed that there is only one fuel. However, in a realistic
fire scenario, there may be many fuel gases generated by the various
burning objects in the building. Specify
the stoichiometry of the predominant reaction via the {\ct REAC}
namelist group. If the stoichiometry of the burning material
differs from the global reaction, the {\ct HEAT\_OF\_COMBUSTION} is
used to ensure that an equivalent amount of fuel is injected into the
flow domain from the burning object.

The heat of combustion can be determined in a couple of ways.
One approach is to take the difference in the heats of formation for the products (assuming complete combustion) and the reactants.
This is typically how values are tabulated for pure fuels (e.g., one species) in handbooks.
This ideal heat of combustion does not account for the  {\ct SOOT\_YIELD} or  {\ct CO\_YIELD} that occurs in a real fire.
Carbon and hydrogen that go to soot and CO rather than CO$_2$ and H$_2$O result in a lower effective heat of combustion.
Setting {\ct IDEAL=.TRUE.} will reduce the {\ct HEAT\_OF\_COMBUSTION} based upon the inputs for {\ct SOOT\_YIELD} and {\ct CO\_YIELD}.
If {\ct EPUMO2} is specified instead of {\ct HEAT\_OF\_COMBUSTION}, then the {\ct EPUMO2} will not be changed.

The second approach to determining the heat of combustion is to burn a known mass of the material in a calorimeter and divide the heat release
rate by the mass loss rate (known as the effective heat of combustion).  In this approach, represented by {\ct IDEAL=.FALSE.},
the measured value of the heat release rate includes the effects of any CO or soot that is produced and no adjustment is needed.  The default value is {\ct IDEAL=.FALSE.}. Note that predefine fuel species have their heat of formation defined; therefore, the heat of combustion for those species will be appropriately adjusted for soot and CO production.

Note: If you specify a heat of combustion on the {\ct REAC} line, FDS will calculate the enthalpy of formation of the fuel such that the user-specified heat of combustion is maintained. This is important to recognize for cases where a heat of combustion is measured experimentally or if you want to model impurities in the fuel that would not be realized using the standard heat of formation of the fuel.

If the reaction is under defined, FDS will return an error at the start of the calculation.


\subsection{Special Topic: Two-Step Simple Chemistry}
\label{info:two-step_simple_chemistry}
\label{propane_flame_2reac}

The default ``simple chemistry'' single-step combustion model has a two-step option. This option is invoked by setting {\ct N\_SIMPLE\_CHEMISTRY\_REACTIONS} to 2 on the {\ct COMB} line. All of the other parameters that are appropriate for the default single-step model are still applicable. The two-step scheme basically takes all of the carbon in the fuel molecule and converts it to CO and Soot in the first step, and then oxidizes most of the CO and Soot to form CO$_2$ in the second step. The hydrogen in the fuel molecule can form either H$_2$ or H$_2$O in the first step as well.
\begin{eqnarray}
  \mathrm{C_xH_yO_zN_v} + \nu_{\text{\tiny \OTWO ,1}} \; \mathrm{O_2} &\longrightarrow& \underbrace{ \nu_{\mathrm{\tiny H_2,1}} \; \mathrm{H_2} + \nu_{\text{\tiny \HTWOO,1}} \; \mathrm{H_2O} + \nu_{\text{\tiny \CO ,1}} \; \mathrm{CO}   + \nu_{\text{\tiny S,1}} \; \mathrm{Soot} + \nu_{\text{\tiny \NTWO ,1}} \; \mathrm{N_2} }_{\rm Int.~Products} \\[0.1in]
   \mathrm{Int.~Products} + \nu_{\text{\tiny \OTWO,2}} \; \mathrm{O_2} &\longrightarrow& \nu_{\text{\tiny \COTWO}} \; \mathrm{CO_2} + \nu_{\text{\tiny \HTWOO ,2}} \; \mathrm{H_2O} + \nu_{\text{\tiny \CO ,2}} \; \mathrm{CO}   + \nu_{\text{\tiny S,2}} \; \mathrm{Soot} + \nu_{\text{\tiny \NTWO ,2}} \; \mathrm{N_2}
\end{eqnarray}
By default, in the first step, two out of three carbon atoms in the fuel are converted to CO. There is not yet a solid basis for this assumption, and the distribution of carbon to CO and Soot can be changed via the parameter {\ct FUEL\_C\_TO\_CO\_FRACTION} on the {\ct COMB} line. It is 2/3, by default. In addition, a fraction of the hydrogen in the fuel molecule can form H$_2$ in the first step. The controlling parameter is called {\ct FUEL\_H\_TO\_H2\_FRACTION} and it is zero by default because this chemistry is not well understood and has been added to the two-step scheme as a placeholder for future research.

Note that the parameters {\ct CO\_YIELD} and {\ct SOOT\_YIELD} retain their meanings from the single-step simple chemistry model; that is, they represent the {\em post-flame} yields of these species. Essentially, the two-step model acknowledges the fact that CO and Soot are present at much higher concentrations within the flame envelop than their post-flame yields would suggest.

The two-step simple chemistry option should only be invoked when you have an interest in near-flame phenomena where the increased concentration of CO and Soot play an important role in the flame chemistry and radiative emission. The resolution of the fire should be reasonably good, as well. What ``reasonably good'' means depends on the particular circumstances, but suffice it to say that you ought to experiment by running simple simulations with and without the two-step option to see if it leads to significantly different results. The cost of the two-step scheme is an additional transport equation for the scalar variable referred to as ``Intermediate Products.''

A simple demonstration of two-step simple chemistry is given by the example cases in the {\ct Species} folder: {\ct propane\_flame\_2reac.fds} and {\ct propane\_flame\_2reac\_simple.fds}. Both cases employ the same two-step reaction scheme:
\begin{eqnarray}
   \mathrm{C_3H_8} + 3 \; \mathrm{O_2} & \longrightarrow & 2 \; \mathrm{CO} + \mathrm{C} + 4 \; \mathrm{H_2O} \\
   2 \; \mathrm{CO} + \mathrm{C} + 4 \; \mathrm{H_2O} + 2 \; \mathrm{O_2} & \longrightarrow & 3 \; \mathrm{CO_2} + 4 \; \mathrm{H_2O}
\end{eqnarray}
The simple version of the input file specifies the combustion parameters as follows:
\begin{lstlisting}
&COMB ..., N_SIMPLE_CHEMISTRY_REACTIONS=2, FUEL_C_TO_CO_FRACTION=0.6667 /
&REAC FUEL='PROPANE', SOOT_YIELD=0., CO_YIELD=0., SOOT_H_FRACTION=0. /
\end{lstlisting}
For simplicity in setting up the complex form of the input file, the post-flame Soot (C) and CO yields are set to zero. Within the flame envelop, Soot and CO are to be generated following the specified \linebreak[4]{\ct FUEL\_C\_TO\_CO\_FRACTION} by which 2 of the 3 carbon atoms in the fuel molecule make up CO, and 1 carbon atom forms Soot with no additional hydrogen ({\ct SOOT\_H\_FRACTION=0}). To check that the two formulations are the same, Fig.~\ref{fig:propane_flame_2reac} displays the heat release and radiative heat release rates for the first few seconds of simulation.
\begin{figure}[!ht]
\begin{center}
\includegraphics[height=2.2in]{SCRIPT_FIGURES/propane_flame_2reac}
\end{center}
\caption[Results of the {\ct propane\_flame\_2reac} test cases]{Demonstration that the simplified form of the two-step simple chemistry input parameters are equivalent to a more complex form.}
\label{fig:propane_flame_2reac}
\end{figure}

\subsection{Special Topic: Complete Heat of Combustion}
\label{info:hoc_complete}

As discussed in Section~\ref{info:solid_pyrolysis} and Section~\ref{info:fuel_droplets}, mass loss of fuel from solids or droplets is adjusted in the gas phase so that the correct total heat release rate is obtained. If a multiple-step reaction scheme, such as discussed in the prior section, is being used, then the {\ct HEAT\_OF\_COMBUSTION} for the {\ct REAC} line of the first step does is not the complete heat of combustion for that fuel. Using this value to adjust mass loss rates would result in an incorrect heat release rate. If a multi-step reaction is being defined and the fuel is being produced by pyrolysis or evaporation, the parameter {\ct HOC\_COMPLETE} should be set on the {\ct REAC} line for the first step. This value will be used for adjusting mass loss rate instead of the {\ct HEAT\_OF\_COMBUSTION}. Note that if two-step simple chemistry is being used, then FDS will automatically compute the value of {\ct HOC\_COMPLETE}.


\subsection{Special Topic: Turbulent Combustion}

\label{info:turbulent_combustion}

Unless you are performing a Direct Numerical Simulation (DNS), the reaction rate of fuel and oxygen is not based on the diffusion of fuel and oxygen at a well-resolved flame sheet. Instead, semi-empirical rules are invoked by FDS to determine the rate of mixing of fuel and oxygen within a given mesh cell at a given time step. Each computational cell can be thought of as a batch reactor where only the mixed composition can react. The variable, $\zeta(t)$, denotes the unmixed fraction, ranging from zero to one and governed by the equation:
\begin{equation}
\frac{\d \zeta}{\d t}=\frac{-\zeta}{\tau_{\rm mix}}
\label{eq:edc_mix}
\end{equation}
Here, $\tau_{\rm mix}$ is the mixing time scale. The change in mass of a species is found from the combination of mixing and the production/destruction rate found from the chemical reaction. If a cell is initially unmixed, $\zeta_0=1$ by default, then combustion is considered non-premixed within the grid cell.  In this case, the fuel and air are considered completely separate at the start of the time step and must mix together before they burn.  This means if the mixing is slow enough, that unburned fuel may exist at the end of the time step even if sufficient oxygen is present in the grid cell to burn all the fuel. If the cell is initially fully mixed, $\zeta_0=0$, then the combustion is considered premixed (e.g., equivalent to infinitely fast mixing). You can set the amount of mixing in each cell at the beginning of every time step using the parameter {\ct INITIAL\_UNMIXED\_FRACTION} on the {\ct COMB} line.

The mixing time, $\tau_{\rm mix}$, is a function of the the level of turbulence in the neighborhood of the point of interest. However, you may override the calculation of $\tau_{\rm mix}$ by setting a {\ct FIXED\_MIX\_TIME} (s) on the {\ct COMB} line. Alternatively, you can bound the computed value of $\tau_{\rm mix}$ by setting a lower bound {\ct TAU\_CHEM} and/or an upper bound {\ct TAU\_FLAME} on the {\ct COMB} line.

Unlike earlier versions, FDS no longer uses the mixture fraction approach for combustion modeling. However, the {\ct 'MIXTURE FRACTION'} output quantity applies the Burke-Schumann solution~\cite{Turns:1996} to map species composition to mixture fraction (i.e., mixture fraction is not a primitive flow variable but rather is calculated from the local fuel and product mass fractions).  This requires simple chemistry with a reaction of the type $\si{F} + \si{A} \rightarrow \si {P}$ with infinitely fast mixing and infinitely fast chemistry.  Therefore, you must set {\ct INITIAL\_UNMIXED\_FRACTION=0} to output {\ct 'MIXTURE FRACTION'}.

The Technical Reference Guide~\cite{FDS_Math_Guide} contains more detailed information about the turbulent combustion model.

\subsection{Special Topic: Flame Extinction}
\label{info:extinction}

Modeling suppression of a fire due to the introduction of a suppression agent like CO$_2$ or water mist, or due to the exhaustion of oxygen within a closed compartment is challenging because the relevant physical mechanisms typically occur at subgrid-scale. Flames are extinguished due to lowered temperatures and dilution of the fuel or oxygen supply. There are two flame extinction models in FDS that determine whether or not combustion is viable based on the cell temperature and the oxygen and fuel concentrations. In brief, for combustion to occur there must be sufficient oxygen and fuel to raise the cell temperature from its current value to a {\em critical flame temperature}.

The {\ct EXTINCTION\_MODEL} is specified on the {\ct COMB} line\footnote{To eliminate any gas phase suppression, set {\ct SUPPRESSION=.FALSE.} on the {\ct COMB} line.}. The {\ct EXTINCTION\_MODEL} called \linebreak[4]{\ct 'EXTINCTION~1'} is the default in Simple Very Large Eddy Simulation (SVLES) mode, whereas \linebreak[4]{\ct 'EXTINCTION~2'} is used in all other modes. The difference between the two models is that for \linebreak[4]{\ct 'EXTINCTION~1'}, only the cell temperature and oxygen concentration are considered because detailed thermophysical gas species properties are not invoked, as they are in the {\ct 'EXTINCTION~2'} model.

The \linebreak[3]{\ct CRITICAL\_FLAME\_TEMPERATURE} (CFT) is based on the {\em oxygen index (OI)} concept discussed in Beyler's chapter in the SFPE Handbook~\cite{SFPE:Beyler}. The oxygen index is the volume fraction of oxygen in the oxidizer stream when extinguishment occurs. The adiabatic flame temperature of a stoichiometric mixture of fuel and oxygen at this limiting oxygen concentration, $T_{\rm OI}$, is taken as the CFT. Values for the CFT ($T_{\rm OI}$) are listed in Table~\ref{tab:CFT}. Both extinction models make use of the CFT. The {\ct 'EXTINCTION~1'} model also uses the {\ct LOWER\_OXYGEN\_LIMIT}, which is sometimes referred to as the {\em lower oxygen index}. It is the oxygen volume fraction at the left end of the solid line in Fig.~\ref{fig:extinct}.

For unlisted fuels, you can set the CFT on the {\ct REAC} line or simply accept the default value, 1427~\si{\degreeCelsius} (1700~K). If you know the oxygen index $X_{\rm OI}$, for a particular fuel, the CFT be calculated from the following equation:
\begin{align}
T_{\rm OI} = T_0 +  X_{\rm OI}  \frac{\Delta H_{\rm c}/r}{n \, \overline{c_p}}
\end{align}
where
\begin{tabbing}
$T_0$     \hspace{0.5in}             \=  Initial temperature of the fuel/air mixture (ambient conditions) (K) \\
$X_{\rm OI}$                         \>  Limiting oxygen volume fraction \\
$\Delta H_{\rm c}/r$                 \>  Heat of combustion per mole of oxygen consumed (kJ/mol)  \\
$n$                                  \>  Number of moles of products of combustion per mole of fuel/air mixture  \\
$\overline{c_p}$                     \>  Average heat capacity (kJ/(mol$\cdot$K)) of products of combustion in the range $T_0$ to $T_{\rm OI}$
\end{tabbing}

\begin{table}[!ht]
\caption[Default Critical Flame Temperatures for common fuels]{Default Critical Flame Temperatures for common fuels.}
\vspace{0.1in}
\label{tab:CFT}
\begin{center}
\begin{tabular}{|l|l|c|c|}
\hline
Fuel              & Formula          & $X_{\rm OI}$    & $T_{\rm OI}$ ($^\circ$C)   \\ \hline \hline
{\ct ACETONE}     & C$_3$H$_6$O      & 0.129        & 1457 \\ \hline
{\ct ACETYLENE}   & C$_2$H$_2$       & 0.085        & 1267 \\ \hline
{\ct BENZENE}     & C$_6$H$_6$       & 0.133        & 1537 \\ \hline
{\ct BUTANE}      & C$_4$H$_{10}$    & 0.134        & 1557 \\ \hline
{\ct ETHANE}      & C$_2$H$_6$       & 0.118        & 1357 \\ \hline
{\ct ETHANOL}     & C$_2$H$_6$O      & 0.126        & 1397 \\ \hline
{\ct ETHYLENE}    & C$_2$H$_4$       & 0.105        & 1337 \\ \hline
{\ct HYDROGEN}    & H$_2$            & 0.054        & 807  \\ \hline
{\ct ISOPROPANOL} & C$_3$H$_8$O      & 0.128        & 1427 \\ \hline
{\ct METHANE}     & CH$_4$           & 0.139        & 1507 \\ \hline
{\ct METHANOL}    & CH$_3$OH         & 0.111        & 1257 \\ \hline
{\ct DECANE}      & C$_{10}$H$_{22}$ & 0.135        & 1507 \\ \hline
{\ct N-HEPTANE}   & C$_7$H$_{16}$    & 0.134        & 1497 \\ \hline
{\ct N-HEXANE}    & C$_6$H$_{14}$    & 0.134        & 1497 \\ \hline
{\ct N-OCTANE}    & C$_8$H$_{18}$    & 0.134        & 1507 \\ \hline
{\ct PROPANE}     & C$_3$H$_8$       & 0.127        & 1447 \\ \hline
All other species &                  & 0.135        & 1427 \\ \hline
\end{tabular}
\end{center}
\end{table}

\subsubsection{Extinction Model Verification}

In the verification case called {\ct Extinction/extinction.fds}, a 10 $\times$ 10 array of small sealed boxes are generated, each with a varying initial temperature from 300~K to 1875~K and initial oxygen mass fraction from 0.0115 to 0.2185, combined with the stoichiometric amount of fuel, and the remainder nitrogen. A one-step, complete reaction of methane is assumed:
\begin{equation}\label{eq:methane_ex}
\mathrm{CH_4 + 2\, O_2 \rightarrow  CO_2 + 2\, H_2O}
\end{equation}
Based on the oxygen and methane concentration and the temperature in each box, combustion can or cannot occur according to the {\ct 'EXTINCTION~2'} model, as shown in Fig.~\ref{fig:extinct}.
\begin{figure}[h!]
\centering
\includegraphics[height=3.2in]{SCRIPT_FIGURES/extinction}
\caption[The \textct{extinction} test case]{Viability of combustion for an array of initial temperatures and oxygen concentrations.}
\label{fig:extinct}
\end{figure}
The FDS predictions based on the {\ct 'EXTINCTION~2'} model confirm that conditions that sustain burning (red crosses) or cause extinction (blue stars) fall closely on the expected results using thermophysical properties of the reactants and products.  The simplified linear model, {\ct 'EXTINCTION~1'}, conforms well with the more detailed calculation. More detailed information on the extinction model can be found in the Technical Reference Guide~\cite{FDS_Tech_Guide}.



\subsection{Special Topic: Piloted Ignition Zone}
\label{info:ignition}

If the mixing-controlled combustion model is used and flame extinction occurs, the unburned fuel gas can re-ignite if it mixes with sufficient oxygen elsewhere in the domain. To prevent this from happening, you can set the {\ct AUTO\_IGNITION\_TEMPERATURE} (AIT) on the {\ct REAC} line, in \si{\degree C}, below which combustion will not occur. Note that if this parameter is used, then some form of heat/ignition source must be present. For most fuels of interest, the AIT may be found in Beyler's chapter of the SFPE Handbook~\cite{SFPE:Beyler}. The default AIT is -273~$^\circ$, meaning that it is possible to get spurious re-ignition of unburned fuel when fresh air is encountered after extinction. Setting an AIT, however, leads to the problem of ignition at a burner surface.  It can be tricky to model the ignition process explicitly because of limited grid resolution. Instead, you can set a fictitiously low value on the {\ct SURF} line that is associated with the burning surface or the {\ct INIT} line that essentially creates a piloted ignition zone in the vicinity of the burning surface. For example, you might use something like this for a piloted methane flame:
\begin{lstlisting}
&REAC FUEL='METHANE', AUTO_IGNITION_TEMPERATURE=627. /
&INIT XB=..., AUTO_IGNITION_TEMPERATURE=-273. /
\end{lstlisting}
The {\ct REAC} line specifies an AIT of 627~\si{\degreeCelsius} throughout the domain except within the region specified by {\ct XB} at the base of the burner where the AIT is effectively turned off. You can achieve a similar end with the following {\ct SURF} line:
\begin{lstlisting}
&REAC FUEL='METHANE', AUTO_IGNITION_TEMPERATURE=627. /
&SURF ..., HRRPUA=..., AUTO_IGNITION_TEMPERATURE=-273. /
\end{lstlisting}

\subsection{Special Topic: Time Ramp of Ignition Temperature}
\label{info:ramp_ait}

The AIT for a given reaction may be ramped in time using {\ct RAMP\_AIT} on the {\ct REAC} line.  The ramp factor {\ct F} is applied to the AIT in Kelvins.  For example, to ramp AIT from -273 \si{\degreeCelsius} to 627 \si{\degreeCelsius} linearly over 10 s use
\begin{lstlisting}
&REAC ID='R1', FUEL='METHANE', AUTO_IGNITION_TEMPERATURE=627., RAMP_AIT='R1 AIT RAMP' /
&RAMP ID='R1 AIT RAMP', T=0., F=0. /
&RAMP ID='R1 AIT RAMP', T=10., F=1. /
\end{lstlisting}



\section{Complex Stoichiometry}
\label{info:REAC_Diagnostics}

The ``simple chemistry'' parameters described above can only be used when there is a single mixing-controlled reaction and the fuel molecule contains only C, O, H, and N.
For any other situation, you must specify the reaction stoichiometry in greater detail. This means that you must explicitly specify the gas species, or species mixtures, along with
the stoichiometry of the reaction.

\subsection{Balancing the Atoms}

Consider a single reaction involving methane. When you specify the {\ct REAC} line to be:

\begin{lstlisting}
&REAC FUEL='METHANE' /
\end{lstlisting}

\noindent FDS assumes the following reaction:
\begin{multline}
1\,\underbrace{\mathrm{ (CH_4) }}_\text{Fuel} \; + \;
9.636 \; \underbrace{ \mathrm{\left( 0.2076 \; O_2 + 0.7825 \; N_2 + 0.0095 \; H_2O + 0.0004 \; CO_2 \right)}}_\text{Air} \longrightarrow \\
10.636 \; \underbrace{\mathrm{(0.0944 \; CO_2 +  0.1966 \; H_2O + 0.7090 \; N_2)}}_\text{Products}
\end{multline}

\noindent By default, there are trace amounts of carbon dioxide and water vapor in the air, which, like the nitrogen, is carried along in the reaction. This is important, because the more complicated way to specify a single step reaction of methane is as follows:

\begin{lstlisting}
&SPEC ID='NITROGEN',       LUMPED_COMPONENT_ONLY=.TRUE. /
&SPEC ID='OXYGEN',         LUMPED_COMPONENT_ONLY=.TRUE. /
&SPEC ID='WATER VAPOR',    LUMPED_COMPONENT_ONLY=.TRUE. /
&SPEC ID='CARBON DIOXIDE', LUMPED_COMPONENT_ONLY=.TRUE. /
&SPEC ID='METHANE' /

&SPEC ID='AIR', BACKGROUND=.TRUE.,
      SPEC_ID(1)='OXYGEN',         VOLUME_FRACTION(1)=0.2076,
      SPEC_ID(2)='NITROGEN',       VOLUME_FRACTION(2)=0.7825,
      SPEC_ID(3)='WATER VAPOR',    VOLUME_FRACTION(3)=0.0095,
      SPEC_ID(4)='CARBON DIOXIDE', VOLUME_FRACTION(4)=0.0004 /

&SPEC ID='PRODUCTS',
      SPEC_ID(1)='CARBON DIOXIDE', VOLUME_FRACTION(1)=0.0944,
      SPEC_ID(2)='WATER VAPOR',    VOLUME_FRACTION(2)=0.1966,
      SPEC_ID(3)='NITROGEN',       VOLUME_FRACTION(3)=0.7090 /

&REAC FUEL='METHANE', SPEC_ID_NU='METHANE','AIR','PRODUCTS',
      NU=-1,-9.636,10.636, HEAT_OF_COMBUSTION=50000. /
\end{lstlisting}

\noindent
The reaction stoichiometry is specified using the stoichiometric coefficients, {\ct NU(N)}, corresponding to the tracked\footnote{A ``tracked'' species is one for which {\ct LUMPED\_COMPONENT\_ONLY} is {\ct .FALSE.}} species, {\ct SPEC\_ID\_NU(N)}. There are several parameters on the {\ct REAC} line that control the specification of the stoichiometry:
\begin{description}
\item[{\ct CHECK\_ATOM\_BALANCE}] If chemical formulas are provided for all species that participate in a reaction, then FDS will check the stoichiometry to ensure that atoms are conserved.  Setting this flag to {\ct .FALSE.} will bypass this check.  (Default {\ct .TRUE.})
\item[{\ct REAC\_ATOM\_ERROR}] Error tolerance in units of atoms for the reaction stoichiometry check.  (Default 0.00001)
\item[{\ct REAC\_MASS\_ERROR}] Relative error tolerance computed as (mass of products - mass of reactants)/(mass of products) for the reaction stoichiometry mass balance check.  (Default 0.0001)
\end{description}



\subsection{Complex Fuel Molecules}
\label{info:Complex_Fuel}

\paragraph{Simple Chemistry Compatible Fuels}

For complex fuel molecules that contain only C, H, N, and O the simple chemistry reaction parameters can still be applied. Consider natural gas, which is often a mixture of several component gases. To build the fuel mixture, the primitive (component) species need be defined. Each primitive species will get a {\ct LUMPED\_COMPONENT\_ONLY} designation, which means that each of these species will not be explicitly tracked as they are components to a mixture.  Note that these lumped components can only contain C, H, N, and O atoms. The lumped fuel, {\ct 'natural gas'}, can be created using the defined primitive components and subsequently the reaction can be defined using simple chemistry (Section \ref{info:simple_chemistry}):
\begin{lstlisting}
&SPEC ID='METHANE',       LUMPED_COMPONENT_ONLY=.TRUE./
&SPEC ID='ETHYLENE',      LUMPED_COMPONENT_ONLY=.TRUE./
&SPEC ID='NITROGEN',      LUMPED_COMPONENT_ONLY=.TRUE./
&SPEC ID='CARBON DIOXIDE',LUMPED_COMPONENT_ONLY=.TRUE./

&SPEC ID='natural gas'
      SPEC_ID(1)='METHANE',       VOLUME_FRACTION(1)=92.2
      SPEC_ID(2)='ETHYLENE',      VOLUME_FRACTION(2)= 3.3
      SPEC_ID(3)='NITROGEN',      VOLUME_FRACTION(3)= 3.9
      SPEC_ID(4)='CARBON DIOXIDE',VOLUME_FRACTION(4)= 0.6/

&REAC FUEL='natural gas'
      SOOT_YIELD=0.01 /
\end{lstlisting}

\paragraph{Non-Simple Chemistry Compatible Fuels}

Fires, however, often involve fuels that do not just consist of C, H, N, and O. For example, chlorine is commonly found in building and household materials, and because
of its propensity to form the acid gas HCl, you may want to account for it in the basic reaction scheme. Suppose the predominant fuel in the fire is polyvinyl chloride (PVC). Regardless of its detailed polymeric structure, it can be regarded as C$_2$H$_3$Cl for the purpose of modeling. Assuming that all of the Cl in the fuel is converted into HCl, you can derive a single-step reaction mechanism using appropriate soot and CO yields for the specified fuel. In this example, the SFPE Handbook~\cite{SFPE:Tewarson} is used to find soot and CO yields for PVC; 0.172 and 0.063, respectively. For a given species, $\alpha$, its stoichiometric coefficient, $\nu_\alpha$, can be found from its yield, $y_\alpha$, and its molecular weight, $W_\alpha$, according to the formula:
\begin{equation}\label{eq:stoic_yield}
\nu_\alpha = \frac{W_{\rm F}}{W_\alpha} \; y_\alpha
\end{equation}
Since it is assumed that all of the Cl is converted to HCL, the remainder of the stoichiometric coefficients come from an atom balance. An equation can now be written to include the appropriate numerical values for the stoichiometric coefficients.
\begin{multline}\label{eq:PVC_reac2}
1\,\underbrace{\mathrm{(C_2H_3Cl)}}_\text{Fuel} + 1\,\underbrace{\mathrm{(1.53 \; O_2 + 1.53 \;(3.76) \; N_2})}_\text{Air} \longrightarrow \\
1\,\underbrace{\mathrm{(HCl +  H_2O + 0.14 \; CO + 0.96 \; CO_2 + 0.90\; C + 1.53\; (3.76) \, N_2)}}_\text{Products}
\end{multline}
The choice of fuel in this example, PVC, is not defined in Table~\ref{tab:gasspecies}, therefore its properties must be defined on a {\ct SPEC} line. In this example, we use the species' chemical formula. The example will also use the lumped species formulation to minimize the number of scalar transport equations that need to be solved. Therefore, each species that does not have an explicit transport equation is a {\ct LUMPED\_COMPONENT\_ONLY}.
\begin{lstlisting}
&SPEC ID = 'PVC', FORMULA = 'C2H3Cl' /
&SPEC ID = 'OXYGEN',            LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'NITROGEN',          LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'HYDROGEN CHLORIDE', LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'WATER VAPOR',       LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'CARBON MONOXIDE',   LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'CARBON DIOXIDE',    LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'SOOT',FORMULA='C',  LUMPED_COMPONENT_ONLY = .TRUE. /
\end{lstlisting}
For the oxidizer and products, which are both composed of multiple primitive species, {\ct SPEC} lines are needed to define the composition of the lumped species. You can define the {\ct SPEC} using either the {\ct MASS\_FRACTIONS} of the component gases or the {\ct VOLUME\_FRACTIONS}. If Eq.~(\ref{eq:PVC_reac2}) is properly balanced, you can directly use the stoichiometric coefficients of the primitive species to define the lumped species.
\begin{lstlisting}
&SPEC ID='AIR', BACKGROUND=.TRUE.
      SPEC_ID(1)='OXYGEN',   VOLUME_FRACTION(1)=1.53,
      SPEC_ID(2)='NITROGEN', VOLUME_FRACTION(2)=5.76 /

&SPEC ID='PRODUCTS',
      SPEC_ID(1)='HYDROGEN CHLORIDE', VOLUME_FRACTION(1)=1.0,
      SPEC_ID(2)='WATER VAPOR',       VOLUME_FRACTION(2)=1.0,
      SPEC_ID(3)='CARBON MONOXIDE',   VOLUME_FRACTION(3)=0.14,
      SPEC_ID(4)='CARBON DIOXIDE',    VOLUME_FRACTION(4)=0.96,
      SPEC_ID(5)='SOOT',              VOLUME_FRACTION(5)=0.90,
      SPEC_ID(6)='NITROGEN',          VOLUME_FRACTION(6)=5.76 /
\end{lstlisting}
To set the initial concentration of fuel, an {\ct INIT} line is used:
\begin{lstlisting}
&INIT MASS_FRACTION(1)=0.229, SPEC_ID(1)='PVC' /
\end{lstlisting}
Since this is not a simple chemistry problem, either the enthalpy of formation of PVC or the heat of combustion of the reaction should be specified. In this case, the heat of combustion for PVC is taken from the SFPE Handbook~\cite{SFPE:Tewarson}.
\begin{lstlisting}
&REAC FUEL='PVC', HEAT_OF_COMBUSTION=16400, SPEC_ID_NU='PVC','AIR','PRODUCTS',
      NU=-1,-1,1, FIXED_MIX_TIME=0.1 /
\end{lstlisting}
Note that the sign of {\ct NU} corresponds to whether that species is consumed (-) or produced (+). Figure~\ref{pvc_combustion} displays the mass fractions of the product species for the sample case {\ct PVC\_Combustion}. Also note that the values for {\ct NU} reflect the composition of the species as defined on the {\ct SPEC} lines. If, for example, the PVC {\ct SPEC} was defined as {\ct CH1.5Cl0.5}, then the {\ct REAC} would require {\ct NU=-2,-1,1}. A fixed turbulent mixing time of 0.1~s is used for this example only because the reactants are initially mixed within a chamber with no imposed flow. Normally, this parameter is not necessary.

\begin{figure}[ht]
\centering \includegraphics[height=2.2in]{SCRIPT_FIGURES/pvc_combustion_spec}
\caption[Results of the {\ct pvc\_combustion} test case]{Product species mass fractions for model PVC example.}
\label{pvc_combustion}
\end{figure}


\subsection{Multiple Fast Reactions}
\label{info:priority}

For large-scale fire simulations, the numerical grid is usually too coarse to resolve detailed, finite-rate flame chemistry. However, you may still specify a combustion scheme that consists of multiple fast reactions. For example, consider this three step scheme that describes the formation of CO and soot as intermediate species in the combustion of propane:
\begin{eqnarray}
\label{eq:propane_3step}
\mathrm{C_3H_8} + \mathrm{3 \, O_2} &\longrightarrow& \mathrm{2 \, CO +  4 \, H_2O + C} \\
\mathrm{CO} + \mathrm{0.5 \, O_2} &\longrightarrow& \mathrm{CO_2} \\
\mathrm{C} + \mathrm{O_2} &\longrightarrow& \mathrm{CO_2}
\end{eqnarray}
In the first step, the fuel is converted quickly to CO, H$_2$O and soot (C), and then the CO and soot are converted to CO$_2$ if there is available oxygen. All the reactions are ``fast'' relative to the mixing time of the reactants within a grid cell, but the second and third reactions are assumed to occur more slowly than the first. By default, FDS forces all fast reactions to occur instantaneously and simultaneously. However, if you want to specify that the reactions occur serially, use the parameter {\ct PRIORITY} as in the following set of input lines:
\begin{lstlisting}
&SPEC ID='NITROGEN',          BACKGROUND=.TRUE. /
&SPEC ID='PROPANE',           MASS_FRACTION_0=0.0 /
&SPEC ID='OXYGEN',            MASS_FRACTION_0=0.23 /
&SPEC ID='WATER VAPOR',       MASS_FRACTION_0=0.0 /
&SPEC ID='CARBON MONOXIDE',   MASS_FRACTION_0=0.0 /
&SPEC ID='CARBON DIOXIDE',    MASS_FRACTION_0=0.0 /
&SPEC ID='SOOT', FORMULA='C', MASS_FRACTION_0=0.0 /

&REAC ID='R1'
      FUEL='PROPANE'
      SPEC_ID_NU='PROPANE','OXYGEN','CARBON MONOXIDE','WATER VAPOR','SOOT'
      SOOT_H_FRACTION=0.
      NU=-1,-3,2,4,1 /
&REAC ID='R2'
      FUEL='CARBON MONOXIDE'
      SPEC_ID_NU='CARBON MONOXIDE','OXYGEN','CARBON DIOXIDE'
      NU=-1,-0.5,1
      PRIORITY=2 /
&REAC ID='R3'
      FUEL='SOOT'
      SPEC_ID_NU='SOOT','OXYGEN','CARBON DIOXIDE'
      NU=-1,-1,1
      PRIORITY=2 /
\end{lstlisting}
By specifying {\ct PRIORITY=2} for reactions {\ct R2} and {\ct R3}, you are assuming that the first reaction, {\ct R1}, occurs first, followed by {\ct R2} and {\ct R3}. This sequence allows for the build-up of soot and CO in compartments that are oxygen starved.

Note that in this reaction scheme, the extinction model is applied to the first reaction but not the second and third because the default extinction model is only applied to the first of multiple fast reactions. For more information on extinction, see Section~\ref{info:extinction}.



\subsection{Multiple Fuels}
\label{info:multi-reac}
\label{energy_budget_adiabatic_two_fuels}

There may be times when your design/model fire is best described by more than one fuel or by more than a single-step chemical reaction. For this example consider two simultaneous, mixing-controlled reactions of polyurethane and wood. Both of these fuels are complex molecules not included in Table~\ref{tab:gasspecies}, so they must be defined on the {\ct SPEC line}. Polyurethane is defined by the chemical formula C$_{25}$H$_{42}$O$_{6}$N$_{2}$ and wood is defined by CH$_{1.7}$O$_{0.74}$N$_{0.002}$. Consider a combustion reaction for polyurethane with a soot yield of $y_{\rm s}$ = 0.131 and a CO yield of $y_{\mathrm{CO}}$= 0.01 \cite{SFPE:Tewarson} is:
\begin{multline}\label{eq:pu_combust}
1\,\underbrace{\mathrm{(C_{25}H_{42}O_{6}N_{2})}}_\text{Fuel} + 27.234364\,\underbrace{\mathrm{(O_2 + 3.76 \; N_2})}_\text{Air} \longrightarrow \\
1\,\underbrace{\mathrm{(19.791134\; CO_2 + 0.166587 \; CO + 20.719873 \; H_2O + 5.602533\; C_{0.9}H_{0.1} + 103.40121 \; N_2)}}_\text{Products\_1}
\end{multline}
and the reaction for wood with a soot yield of $y_{\rm s}$ = 0.015 and a CO yield of $y_{\mathrm{CO}}$= 0.004 \cite{SFPE:Tewarson} is:
\begin{multline}\label{eq:wood_combust}
1\,\underbrace{\mathrm{(CH_{1.7}O_{0.74}N_{0.002})}}_\text{Fuel} + 1.020627\,\underbrace{\mathrm{(O_2 + 3.76 \; N_2})}_\text{Air} \longrightarrow \\
1\,\underbrace{\mathrm{(0.964679\; CO_2 + 0.003655 \; CO + 0.848241 \; H_2O + 0.035184\; C_{0.9}H_{0.1} + 3.838558 \; N_2)}}_\text{Products\_2}
\end{multline}
Similar to example in Section~\ref{info:Complex_Fuel}, we will use the lumped species approach to minimize the number of species that FDS needs to transport. Therefore, the species are defined in the following manner:
\begin{lstlisting}
&SPEC ID = 'POLYURETHANE', FORMULA = 'C25H42O6N2' /
&SPEC ID = 'WOOD', FORMULA = 'CH1.7O0.74N0.002' /
&SPEC ID = 'OXYGEN',            LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'NITROGEN',          LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'WATER VAPOR',       LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'CARBON MONOXIDE',   LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'CARBON DIOXIDE',    LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'SOOT',              LUMPED_COMPONENT_ONLY = .TRUE. /
\end{lstlisting}
Examination of Eq.~(\ref{eq:pu_combust}) and Eq.~(\ref{eq:wood_combust}) shows that, while Products\_1 and Products\_2 are composed of the same species, the species do not exist in the same proportion. As a result, we must construct two separate product lumped species.
\begin{lstlisting}
&SPEC ID = 'AIR',
      SPEC_ID(1) = 'OXYGEN',   VOLUME_FRACTION(1)=1,
      SPEC_ID(2) = 'NITROGEN', VOLUME_FRACTION(2)=3.76,
      BACKGROUND=.TRUE. /

&SPEC ID = 'PRODUCTS_1',
      SPEC_ID(1) = 'CARBON DIOXIDE',  VOLUME_FRACTION(1) = 19.79113,
      SPEC_ID(2) = 'CARBON MONOXIDE', VOLUME_FRACTION(2) = 0.166587,
      SPEC_ID(3) = 'WATER VAPOR',     VOLUME_FRACTION(3) = 20.71987,
      SPEC_ID(4) = 'SOOT',            VOLUME_FRACTION(4) = 5.60253,
      SPEC_ID(5) = 'NITROGEN',        VOLUME_FRACTION(5) = 103.40121 /

&SPEC ID = 'PRODUCTS_2',
      SPEC_ID(1) = 'CARBON DIOXIDE',  VOLUME_FRACTION(1) = 0.964679,
      SPEC_ID(2) = 'CARBON MONOXIDE', VOLUME_FRACTION(2) = 0.003655,
      SPEC_ID(3) = 'WATER VAPOR',     VOLUME_FRACTION(3) = 0.848241,
      SPEC_ID(4) = 'SOOT',            VOLUME_FRACTION(4) = 0.035184,
      SPEC_ID(5) = 'NITROGEN',        VOLUME_FRACTION(5) = 3.838558 /
\end{lstlisting}
Once we have constructed the lumped species, we can define the {\ct REAC} lines.
\begin{lstlisting}
&REAC ID = 'plastic',
      FUEL = 'POLYURETHANE',
      HEAT_OF_COMBUSTION=26200,
      SPEC_ID_NU = 'POLYURETHANE','AIR','PRODUCTS_1'
      NU=-1,-27.23436,1 /

&REAC ID = 'wood'
      FUEL = 'WOOD',
      HEAT_OF_COMBUSTION=16400,
      SPEC_ID_NU = 'WOOD','AIR','PRODUCTS_2'
      NU=-1,-1.02063,1 /
\end{lstlisting}
In both of these reactions, the {\ct ENTHALPY\_OF\_FORMATION} of the chosen fuels is unknown to FDS, so the {\ct HEAT\_OF\_COMBUSTION} is specified for each reaction. Typically, the heat release per unit area ({\ct HRRPUA}) parameter is used to specify the fire size on the {\ct SURF} line. The {\ct HRRPUA} parameter cannot currently be used when there is more than one fuel, so the mass flux of fuel must be specified for each fuel. In this example, we want both fuels to flow out of the same burner and ramp up to a 1200~kW fire after 60~s. First, we create a 1~m$^2$ burner by defining a {\ct VENT} line:
\begin{lstlisting}
&VENT XB=4.0,5.0,4.0,5.0,0.0,0.0, SURF_ID='FIRE1', COLOR='RED'/
\end{lstlisting}
The {\ct VENT} points to the {\ct SURF\_ID='FIRE1'} which we can define using both fuels. The mass flux values for each fuel are determined by the desired heat release, the proportion of the total heat release rate each fuel contributes, the burner area, and the heat of combustion of each fuel. In this case we want a 1200~kW fire where each fuel contributes 50\% to the total heat release rate (600~kW).
\begin{align}
\dot{m}''_{\rm poly} &= \frac{600~\mathrm{kW}}{1~\mathrm{m^2}}\frac{1}{26200~\si{kJ/kg}} = 0.022901~\si{kg/(m^2.s)}\\
\dot{m}''_{\rm wood} &= \frac{600~\mathrm{kW}}{1~\mathrm{m^2}}\frac{1}{16400~\si{kJ/kg}} = 0.036585~\si{kg/(m^2.s)}
\end{align}

\begin{lstlisting}
&SURF ID='FIRE1', SPEC_ID(1)='POLYURETHANE', MASS_FLUX(1)=0.022901, RAMP_MF(1)='poly'
                  SPEC_ID(2)='WOOD',         MASS_FLUX(2)=0.036585, RAMP_MF(2)='wood'/
\end{lstlisting}
Note that the {\ct SPEC\_ID}, {\ct MASS\_FLUX}, and {\ct RAMP\_MF} correspond to one another for each fuel. It does not matter which fuel is {\ct (1)}, just that the numbering is consistent. We also want each fuel to follow a ramp such that fire starts at 0~kW at the initial time, reaches 1200~kW at 100~s, and remains at 1200~kW for the remainder of a 600~s simulation.
\begin{lstlisting}
&RAMP ID='poly', T = 0,   F = 0.0 /
&RAMP ID='poly', T = 50 , F = 0.5 /
&RAMP ID='poly', T = 100, F = 1.0 /
&RAMP ID='poly', T = 600, F = 1.0 /

&RAMP ID='wood', T = 0  , F = 0.0 /
&RAMP ID='wood', T = 50 , F = 0.5 /
&RAMP ID='wood', T = 100, F = 1.0 /
&RAMP ID='wood', T = 600, F = 1.0 /
\end{lstlisting}
Here, {\ct T} corresponds to the time and {\ct F} is the fraction of the mass flux specified on the {\ct SURF} line. Fig.~\ref{fig:hrr_two_fuels} compares the resulting FDS heat release rate (HRR) to the expected HRR from the defined ramp. Note that in this simulation, there is 10~s averaging on the FDS output HRR ({\ct \&DUMP DT\_HRR=10}) and the expected results account for this averaging.

\begin{figure}[ht]
\centering
\includegraphics[width=3.2in]{SCRIPT_FIGURES/energy_budget_adiabatic_two_fuels}
\caption[HRR for {\ct energy\_budget\_adiabatic\_two\_fuels} test case]{HRR for {\ct energy\_budget\_adiabatic\_two\_fuels} test case.}
\label{fig:hrr_two_fuels}
\end{figure}
Note that when using multiple chemical reactions, you must set {\ct SUPPRESSION=.FALSE.} on the {\ct COMB} line.

\subsection{Special Topic: Using the {\ct EQUATION} input parameter}
\label{info:EQUATION}

When specifying a reaction scheme using all primitive variables ({\em i.e., no lumped species}), a convenient shortcut for specifying the reaction is via the input parameter {\ct EQUATION}, which allows the specification of the reaction in text form.  The rules are:

\begin{itemize}
\item The species must be explicitly tracked.
\item The species name is its chemical formula as defined on the {\ct SPEC} line or by the species {\ct ID}.
\item The stoichiometry is given before each species and is separated by an asterisk. Real numbers are allowed but exponential notation is not (i.e., {\ct 201.1} but not {\ct 2.011E2}).
\item The reactants and products are separated by an equals sign.
\end{itemize}

\noindent For example, if the reaction defines the complete combustion of methane using primitive species, then the following would be equivalent:

\begin{lstlisting}
&REAC FUEL='METHANE', EQUATION ='METHANE+2*OXYGEN=CARBON DIOXIDE+2*WATER VAPOR' /
&REAC FUEL='METHANE', EQUATION ='CH4+2*O2=CO2+2*H2O' /
&REAC FUEL='METHANE', EQUATION ='METHANE+2*O2=CO2+2*H2O' /
\end{lstlisting}



\newpage

\section{Finite Rate Combustion}
\label{info:finite}

By default, FDS uses a mixing-controlled combustion model, meaning that the reaction rate is infinite and limited only by species concentrations. However, FDS can also employ finite-rate reactions using an Arrhenius model. It is recommended that finite-rate reactions be invoked only when FDS is running in DNS mode ({\ct DNS=.TRUE.} on the {\ct MISC} line). You can use the finite-rate reaction model in an LES calculation, but because the temperature in a large scale calculation is smeared out over a mesh cell, some of the reaction parameters may need to be modified to account for the lower cell-averaged temperatures.

\subsubsection{Single Step Reaction}

Consider a single-step reaction mechanism for complete propane combustion:
\begin{equation}\label{eq:propane_1step}
\mathrm{C_3H_8 + 5\,O_{2} \rightarrow 3\,CO_{2} + 4\,H_{2}O}
\end{equation}
In this case, we explicitly define all primitive species:
\begin{lstlisting}
&SPEC ID='NITROGEN', BACKGROUND=.TRUE./
&SPEC ID='PROPANE' /
&SPEC ID='OXYGEN' /
&SPEC ID='WATER VAPOR' /
&SPEC ID='CARBON DIOXIDE' /
\end{lstlisting}
The rate expression for the fuel, $\mathrm{C_3H_8}$, is
\begin{equation}\label{eq:finite_rate}
\frac{\d C_{\mathrm{C_3H_8}}}{\d t}= -k \, \prod C_{\alpha}\,^{N_{S,\alpha}}
\end{equation}
where $C_\alpha$ is the concentration of species $\alpha$ in units of mol/cm$^3$ and the rate constant is defined as
\begin{equation}\label{eq:reac_rate}
k = A \, T^{N_{T}} \, {\rm e}^{-E_a/RT}
\end{equation}
\begin{description}
\item[$A$] is the pre-exponential factor [\,((\si{mol/cm^3})$^{1-n}$)/s\,], where $n=\sum N_{S,\alpha}$ is the \emph{order} of the reaction,
\item[$E_a$] is the activation energy [\,\si{J/mol}\,],
\item[$N_{S,\alpha}$] is an array containing the concentration exponents (default 1),
\item[$N_T$] is the temperature exponent (default 0, meaning no temperature dependence),
\item[$R$] is the universal gas constant, 8.314~J/(mol$\cdot$K).
\end{description}
If we use Arrhenius parameters found from experiments or the literature (for this case Westbrook and Dryer~\cite{Westbrook:1}), the rate expression for the single-step propane reaction defined by Eq.~(\ref{eq:propane_1step}) becomes:
\begin{equation}\label{eq:reac_rate2}
\frac{\d C_{\mathrm{C_3H_8}}}{\d t} = -8.6 \times 10^{11} \; T^{0} \; {\rm e}^{-125520/RT} \; C_{\mathrm{C_3H_8}}\,^{0.1} \; C_{\mathrm{O_2}}\,^{1.65}
\end{equation}
and the resulting {\ct REAC} line is:
\begin{lstlisting}
&REAC ID = 'R1'
      FUEL = 'PROPANE'
      A = 8.6e11
      E = 125520
      SPEC_ID_NU = 'PROPANE','OXYGEN','CARBON DIOXIDE','WATER VAPOR'
      NU = -1,-5,3,4
      SPEC_ID_N_S = 'PROPANE','OXYGEN'
      N_S = 0.1,1.65 /
\end{lstlisting}
The array {\ct SPEC\_ID\_NU} contains the list of tracked species participating in the reaction as a product or reactant.  Note that a primitive species with {\ct LUMPED\_COMPONENT\_ONLY=.TRUE.} cannot be used in a reaction since it is not tracked separately.  The array {\ct SPEC\_ID\_N\_S} contains the list of species with the exponents, {\ct N\_S}, in Eq.~(\ref{eq:finite_rate}).  This array must contain only primitive species, i.e., no species mixtures. The array of stoichiometric coefficients, {\ct NU}, can be taken directly from Eq.~(\ref{eq:propane_1step}).

\subsection{Multiple Step Reaction}

If we extend Eq.~(\ref{eq:propane_1step}) to include reactions from Westbrook and Dryer~\cite{Westbrook:1} that account for carbon monoxide production, we obtain:
\begin{align}\label{eq:propane_2step}
\mathrm{C_3H_8+3.5 \, O_2}&\rightarrow  \mathrm{3\,CO+4 \, H_2O} \\
\nonumber \mathrm{CO + 0.5 \, O_2} &\leftrightharpoons \mathrm{CO_2}
\end{align}
In this case we will combine fast chemistry with finite-rate chemistry to create a mixed reaction mechanism. As before, we use primitive species rather than mixtures. A {\ct REAC} line is needed for each reaction including the reverse reaction. The propane oxidation reaction is a fast chemistry while the reversible carbon monoxide reaction is finite-rate. The Arrhenius parameters are modified from Andersen et al.~\cite{AndersenJ:1}:
\begin{lstlisting}
&REAC ID = 'R1'
      FUEL = 'PROPANE'
      SPEC_ID_NU = 'PROPANE','OXYGEN','CARBON MONOXIDE','WATER VAPOR'
      NU = -1,-3.5,3,4 /

&REAC ID = 'R2'
      FUEL = 'CARBON MONOXIDE'
      A = 1.5e9
      E = 41840
      SPEC_ID_NU = 'CARBON MONOXIDE','OXYGEN','CARBON DIOXIDE'
      NU = -1,-0.5,1
      SPEC_ID_N_S = 'OXYGEN','CARBON MONOXIDE','WATER VAPOR'
      N_S = 0.25,1,0.5 /

&REAC ID = 'R3'
      FUEL = 'CARBON DIOXIDE'
      A = 6.16e13
      E = 328026
      SPEC_ID_NU = 'CARBON DIOXIDE','OXYGEN','CARBON MONOXIDE'
      NU = -1,0.5,1
      SPEC_ID_N_S = 'OXYGEN','CARBON DIOXIDE','WATER VAPOR'
      N_S = -0.25,1,0.5
      N_T = -0.97 /
\end{lstlisting}
For the reaction R2, the reaction rate depends on the water vapor concentration, as indicated by its assignment of a value of {\ct N\_S}. However, it does not explicitly participate in the reaction because it is not assigned a stoichiometric coefficient, {\ct NU}.  Reactions of this sort are often written in textbooks as
\begin{equation}\label{eq:inert_1step}
\mathrm{a \, X + b \, Y \overset{H_2O}{\longrightarrow} X_aY_b}
\end{equation}
However, for the purposes of inputting into FDS, since H$_2$O is neither a product nor a reactant it would not be specified in the chemical reaction using either {\ct EQUATION} or {\ct NU}.  It would instead be given a rate exponent using {\ct N\_S} to indicate that its presence is required.

As discussed previously (Section~\ref{info:heat_of_combustion}), energy release is calculated using the net change of species in a time step along with the enthalpy of formation of each species. This approach makes specifying an endothermic reaction, such as the reversible CO$_2$ reaction (R3), no different than typical FDS exothermic combustion reactions.

\subsection{Catalysts}

Some reactions require the presence of any third body to stabilize the reaction rather than just a specific species.  Reactions of this type are often write in textbooks as
\begin{equation}\label{eq:third_body}
\mathrm{a \, X + b \, Y + M \rightarrow X_aY_b + M }
\end{equation}
This type of reaction is specified by adding {\ct THIRD\_BODY=.TRUE.} to the {\ct REAC} line for the reaction.  The species M should not otherwise be defined.



\subsection{Special Topic: Chemical Time Integration}
\label{info:chem_integration}

The set of ordinary differential equations (ODEs) for the combustion reactions are solved over the course of a time step using one of a variety of solvers. The solver is specified via the character string {\ct ODE\_SOLVER} on the {\ct COMB} line. The chosen solver governs all reactions. If all reactions are fast, i.e. occur instantaneously following the mixing process, then the default solver is {\ct 'EXPLICIT EULER'}. If any of the reactions are finite-rate, then the default solver is {\ct 'RK2 RICHARDSON'}, a fourth-order scheme generated from three second-order Runge-Kutta steps with Richardson extrapolation (the third step provides a means of error control; details are provided in the of the FDS Tech Guide \cite{FDS_Math_Guide}). Two other schemes are available---{\ct 'RK2'} and {\ct 'RK3'}, second and third-order Runge-Kutta schemes without Richardson extrapolation.

An important consideration for the time integration of chemical reactions is the number of iterations the ODE solver takes for a given FDS time step. For infinitely fast chemistry, the number of iterations is 1. For finite rate chemical reactions, the number of iterations can vary between 1 and the lesser of\linebreak[4] {\ct MAX\_CHEMISTRY\_SUBSTEPS} (default 20) and that needed to satisfy the error tolerance of the ODE solver,\linebreak[4] {\ct RICHARDSON\_ERROR\_TOLERANCE}. If the maximum value is reached, you can increase the number of iterations or decrease the error tolerance constraint of the integrator. You may also just fix the number of iterations by setting {\ct N\_FIXED\_CHEMISTRY\_SUBSTEPS}. Its default value is -1, meaning that the number of time steps is determined by the ODE solver. These various numerical parameters are all set on the {\ct COMB} line, and they pertain to all reactions.

If you have multiple reactions with widely ranging time-scales, you might want to specify \linebreak[4]{\ct CHECK\_REALIZABILITY} to be {\ct .TRUE.} on the {\ct COMB} line, which forces the program to issue a warning if the species mass fractions do not remain between 0 and 1 during the integration scheme.



\newpage

\section{Special Topic: Aerosol Deposition}
\label{info:deposition}

It is possible within FDS to model the deposition of smoke and aerosols onto solid surfaces. The aerosol deposition model is invoked by defining a species with the parameter {\ct AEROSOL=.TRUE.} on the {\ct SPEC} line along with the parameters {\ct DENSITY\_SOLID}, {\ct CONDUCTIVITY\_SOLID}, and {\ct MEAN\_DIAMETER}. By default, with {\ct AEROSOL=.TRUE.}, FDS will compute all of the aerosol deposition mechanisms discussed in the Technical Reference Guide~\cite{FDS_Math_Guide}. For diagnostic purposes, each surface deposition mechanism can be selectively disabled by using the logical parameters {\ct GRAVITATIONAL\_DEPOSITION}, {\ct THERMOPHORETIC\_DEPOSITION}, and {\ct TURBULENT\_DEPOSITION}. All surface deposition can be disabled by the logical parameter {\ct DEPOSITION}. In the gas phase, aerosol transport is affected by gravity and temperature gradients. These effects can be selectively disabled with {\ct GRAVITATIONAL\_SETTLING} and {\ct THERMOPHORETIC\_SETTLING}. All the deposition parameters are on the {\ct MISC} line.  The deposition velocity at the wall can be output using the solid phase output {\ct QUANTITY} called {\ct 'DEPOSITION VELOCITY'}.

\subsection{Example Case: Soot Deposition from a Propane Flame}

The {\ct propane\_flame\_deposition} example shows how to define a reaction that invokes the aerosol deposition model in FDS. The fuel is propane with a specified soot yield of 0.05. Note that this is a fabricated soot yield that is used only for demonstration and verification purposes. The reaction is given by:
\begin{multline}\label{eq:PROPANE_depo}
1\,\underbrace{\mathrm{(C_3H_8)}}_\text{Fuel} \,+\, 4.81308 \; \underbrace{\mathrm{(O_2\,+\, 3.7619 \; N_2})}_\text{Air} \, \longrightarrow \\
1 \; \underbrace{\mathrm{(18.10631 \; N_2 \, + \, 2.81813 \; CO_2 \,+ \, 3.98990\; H_2O)}}_\text{Products} \,+\,
\,0.20201 \; \underbrace{\mathrm{C_{0.9}H_{0.1}}}_\text{Soot}
\end{multline}
Note that the stoichiometric coefficient for soot ensures that the mass of soot produced is 0.05 times the mass of fuel consumed. This example uses the lumped species formulation to minimize the number of scalar transport equations that need to be solved. Note that for soot to deposit it must be explicitly tracked by defining {\ct AEROSOL=.TRUE.} on the {\ct SPEC} line.
\begin{lstlisting}
&SPEC ID = 'PROPANE' /
&SPEC ID = 'OXYGEN',            LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'NITROGEN',          LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'WATER VAPOR',       LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'CARBON DIOXIDE',    LUMPED_COMPONENT_ONLY = .TRUE. /
&SPEC ID = 'SOOT',              AEROSOL = .TRUE. /
\end{lstlisting}
If Eq.~(\ref{eq:PROPANE_depo}) is properly balanced, you can directly use the stoichiometric coefficients of the primitive species to define the lumped species:

\begin{lstlisting}
&SPEC ID = 'AIR', SPEC_ID ='NITROGEN','OXYGEN',
      VOLUME_FRACTION = 3.7619,1., BACKGROUND = .TRUE. /
&SPEC ID = 'PRODUCTS', SPEC_ID ='NITROGEN','CARBON DIOXIDE','WATER VAPOR',
      VOLUME_FRACTION = 18.10631,2.81813,3.98990 /
\end{lstlisting}

\noindent
The heat of combustion for propane is found in the SFPE Handbook~\cite{SFPE:Tewarson}.

\begin{lstlisting}
&REAC FUEL = 'PROPANE', HEAT_OF_COMBUSTION=44715.,
      SPEC_ID_NU = 'PROPANE','AIR','PRODUCTS','SOOT',
      NU=-1.,-4.81308,1,0.20208/
\end{lstlisting}

\noindent
Note: The sign of {\ct NU} corresponds to whether that species is consumed (-) or produced (+). Figure~\ref{soot_deposition} shows the soot surface deposition on the wall.  This boundary quantity is given by the input below.

\begin{lstlisting}
&BNDF QUANTITY='SURFACE DEPOSITION', SPEC_ID='SOOT' /
\end{lstlisting}

\begin{figure}[ht]
\centering
\includegraphics[width=3.2in]{SCRIPT_FIGURES/propane_flame_deposition}
\caption[Wall soot deposition for the {\ct propane\_flame\_deposition} test case]{Wall soot deposition for the {\ct propane\_flame\_deposition} test case.}
\label{soot_deposition}
\end{figure}


\subsection{Soot Surface Oxidation}

If soot deposition is being computed, the soot present on surfaces can undergo oxidation if the local temperature is high enough and oxygen is present. Soot oxidation is enabled with the logical flag {\ct SOOT\_OXIDATION} on the {\ct MISC} input. Oxidation is computed as a single step, Arrhenius reaction using the soot surface density and the local oxygen mole fraction. The reaction uses a rate constant of $4.7 \times 10^{12}$ and an activation energy of 211~kJ/mol. These values are based upon work performed by Hartman, Beyler, Riahi, and Beyler~\cite{Hartman_2012}.


\section{Special Topic: Aerosol Agglomeration}
\label{info:agglomeration}

Aerosol particles will, over time, collide with one another and stick together to form larger particles. This process is called agglomeration. The agglomeration model in FDS is automatically invoked by defining an aerosol species with size bins. The agglomeration model can be disabled the logical flag {\ct AGGLOMERATION} on the {\ct MISC} input. Particle bins are defined by giving a minimum particle diameter, {\ct MIN\_DIAMETER} in $\mu$m, a maximum particle diameter, {\ct MAX\_DIAMETER} in $\mu$m, and the desired number of size bins, {\ct N\_BINS}, on the {\ct SPEC} line for an aerosol species. Note that if multiple aerosol species are defined, the agglomeration model will agglomerate each species independently, that is particles of different species do not agglomerate together into a larger mixed-species particle. The following input defines a soot species as an aerosol with 10 bins between 1 and 100~$\mu$m. Each bin will be created as its own lumped species with names {\ct SOOT\_1} through {\ct SOOT\_10}. A summary of the particle bins will be written to the {\ct CHID.out} file.

\begin{lstlisting}
&SPEC ID='SOOT', AEROSOL=.TRUE.,MIN_DIAMETER=1.E-6,MAX_DIAMETER=100.E-6,
      N_BINS=10,LUMPED_COMPONENT_ONLY=.TRUE./
\end{lstlisting}

\chapter{Radiation}

\section{Basic Radiation Parameters: The \texorpdfstring{{\tt RADI}}{RADI} Namelist Group}
\label{info:RADI}
\label{info:CHI_R}

{\ct RADI} is the namelist group that contains parameters related to the radiation solver. There can be only one {\ct RADI} line in the input file.

An important quantity in fire science is the fraction of the fire's heat release rate released in the form of thermal radiation, commonly referred to as the {\em radiative fraction}, symbolically denoted $\chi_{\rm r}$. It is a function of the fire size, flame temperature, and the chemical composition of the fuel and combustion products. The flame temperature, as opposed to the average cell temperature, is not reliably calculated in a large scale fire simulation because the flame sheet is not well-resolved on a relatively coarse numerical grid. Thus, the source term in the radiation transport equation (RTE), because of its $T^4$ dependence, cannot be reliably calculated. As a practical alternative, the parameter {\ct RADIATIVE\_FRACTION} on the {\ct REAC} or {\ct COMB} line allows you to specify explicitly the fraction of the total combustion energy that is released in the form of thermal radiation.  By default, the {\ct RADIATIVE\_FRACTION} is set to a specific value that is based on the reaction's {\ct FUEL} for an LES calculation, and it is set to zero for DNS, in which case the amount of energy radiated by the fire is predicted rather than prescribed. Table~\ref{tab:chi_r} lists the default radiative fraction for some common pure fuels. Many of these values are based on measurements performed on relatively small flames by Tewarson~\cite{SFPE:Tewarson}. These values may change with increasing fire size; thus, the measurements cited by Beyler~\cite{Beyler2:SFPE} may be more appropriate for larger fires. If in doubt, select the value that is appropriate for your fire. There is no single value of radiative fraction for a given fuel.

\vspace{\baselineskip}

\noindent There are four ways of treating thermal radiation in FDS, as explained in the following sections.

\begin{table}[!ht]
\caption[Default radiative fraction for some common fuels]{Default radiative fraction for some common fuels.}
\label{tab:chi_r}
\begin{center}
\begin{tabular}{|l|c|c|}
\hline
Species                  & $\chi_{\rm r}$   & Reference                               \\ \hline \hline
{\ct ACETONE}            & 0.27             & \cite{SFPE:Tewarson}                    \\ \hline
{\ct ACETYLENE}          & 0.49             & \cite{SFPE:Tewarson}                    \\ \hline
{\ct BENZENE}            & 0.60             & \cite{SFPE:Tewarson}                    \\ \hline
{\ct BUTANE}             & 0.30             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct DODECANE}           & 0.40             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct ETHANE}             & 0.25             & \cite{SFPE:Tewarson}                    \\ \hline
{\ct ETHANOL}            & 0.25             & \cite{SFPE:Tewarson}                    \\ \hline
{\ct ETHYLENE}           & 0.25             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct HYDROGEN}           & 0.20             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct ISOPROPANOL}        & 0.29             & \cite{SFPE:Tewarson}                    \\ \hline
{\ct METHANE}            & 0.20             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct METHANOL}           & 0.16             & \cite{SFPE:Tewarson}                    \\ \hline
{\ct N-DECANE}           & 0.40             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct N-HEPTANE}          & 0.40             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct N-HEXANE}           & 0.40             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct N-OCTANE}           & 0.40             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct PROPANE}            & 0.30             & \cite{Beyler2:SFPE}                     \\ \hline
{\ct PROPYLENE}          & 0.37             & \cite{SFPE:Tewarson}                    \\ \hline
{\ct TOLUENE}            & 0.40             & \cite{Hamins:NISTIR7013}                \\ \hline
All other species        & 0.35             &                                         \\ \hline
\end{tabular}
\end{center}
\end{table}

\subsection{Radiation Option 1. No Radiation Transport}
\label{info:radiation_off}

It is possible to turn off the RTE solver (saving roughly 20 \% in CPU time) by adding the statement {\ct RADIATION=.FALSE.} to the {\ct RADI} line.  If burning is taking place and radiation is turned off, then the total heat release rate is reduced by the {\ct RADIATIVE\_FRACTION}, which is an input on the {\ct REAC} or {\ct COMB} line. Default values for various pure fuels are listed in Table~\ref{tab:chi_r}. With {\ct RADIATION} set to {\ct .FALSE.}, the radiated energy from a fire simply disappears from the computational domain. For fire simulations or any scenario with temperature increases of hundreds of degrees Celsius, it is not recommended that you turn off the radiation transport. This feature is used mainly for diagnostic purposes or when the changes in temperature are relatively small.

\subsection{Radiation Option 2. Optically-Thin Limit; Specified Radiative Fraction}

There are some fire scenarios where you might want to set the absorption coefficient in the RTE, $\kappa$, to zero by setting {\ct OPTICALLY\_THIN} to {\ct .TRUE.} on the {\ct RADI} line, in which case reabsorption of thermal radiation by cold combustion product gases is neglected. Essentially, the fire radiates the user-specified {\ct RADIATIVE\_FRACTION} of energy, and this energy is transported to the domain boundaries without being reabsorbed by colder gases. This is not something you want to do for a compartment fire scenario, where absorption and emission of thermal radiation by hot and cold smoke is an important consideration. Rather, you might want to choose this option for scenarios where you have a fire outside of a compartment or in a relatively large open space and you want to explicitly dictate the net radiation energy that is transported to targets and solid boundaries. For example, the radiative fraction of very large hydrocarbon fuel fires can decrease with increasing diameter because of the re-absorption of radiated energy by the smoke and combustion products. This is why a large oil fire appears to be comprised mostly of smoke, and this smoke shields external objects from the thermal radiation. Predicting this phenomenon is difficult and can be grid-dependent. In such cases, you may want to just specify the {\ct RADIATIVE\_FRACTION} on the {\ct REAC} or {\ct COMB} line and then {\ct OPTICALLY\_THIN=.TRUE.} on the {\ct RADI} line, in which case the fire will radiate the given fraction of energy and FDS will not attempt to calculate the re-absorption of this energy by the combustion products.

\subsection{Radiation Option 3. Optically-Thick; Specified Radiative Fraction (LES Default)}

In its normal operation, the RTE transfers energy from hot, emitting gases, like flames, to colder, absorbing gases like water vapor or soot particulate. The absorption coefficient, $\kappa$, computed using RadCal, governs both the emission and absorption of thermal radiation. Because flame temperatures are not well-resolved for typically large-scale fire simulations, the source term in the RTE is adjusted in grid cells for which the radiative fraction, $\chi_{\rm r}$, times the local heat release rate per unit volume, $\dot{q}'''$, is greater than 10~kW/m$^3$
\be
   \chi_{\rm r} \, \dot{q}''' > 10 \; \hbox{kW/m}^3 \label{clip}
\ee
The adjustment ensures that the net radiative emission from the combusting region (i.e. the fire) is the specified {\ct RADIATIVE\_FRACTION} multiplied by the total combustion energy generated in this region. Elsewhere, hot and cold gases emit and absorb thermal radiation according to their bulk temperature and radiative properties, in particular the absorption coefficient, $\kappa$.

The net radiative loss from the computational domain is reported as a function of time in the column {\ct Q\_RADI} in the output file {\ct CHID\_hrr.csv}. The absolute value of {\ct Q\_RADI} divided by the total heat release rate, {\ct HRR}, is usually not exactly equal to the specified {\ct RADIATIVE\_FRACTION}. The reason for this is that the specified radiative fraction of the fire's energy can be reabsorbed by colder combustion products such as smoke and water vapor, thereby decreasing the absolute value of {\ct Q\_RADI}. Or, hot layer smoke and combustion products can heat up and emit thermal radiation, adding to the absolute value of {\ct Q\_RADI}.

The correction factor that is applied to the RTE source term in the region defined by Eq.~(\ref{clip}) by default is bound between 1 and 100, meaning that the correction factor only increases the net radiative output of the combusting region, if necessary, to achieve the desired {\ct RADIATIVE\_FRACTION}. However, you can change the default behavior of the correction as follows. First, you can force the RTE source term to be modified in all grid cells by changing the 10 in Eq.~(\ref{clip}) to -1 via {\ct QR\_CLIP} on the {\ct RADI} line, in which case the solver will apply the radiative fraction to the entire domain, not just the cells where combustion occurs. This will essentially force the net radiative loss from the entire domain to obey the {\ct RADIATIVE\_FRACTION}. Second, you can allow the RTE source term to increase or decrease in value to achieve the desired {\ct RADIATIVE\_FRACTION} by changing the lower limit of the correction factor, {\ct C\_MIN}, from its default value of 1 to, say, 0.5 on the {\ct RADI} line. The corresponding parameter, {\ct C\_MAX}, limits the correction factor to 100.

\subsection{Radiation Option 4. Optically-Thick; Unspecified Radiative Fraction (DNS Default)}

If it can be assumed that the temperature field is well-resolved and the radiation absorption coefficient and RTE source term can be calculated without correction, then {\ct RADIATIVE\_FRACTION} ought to be set to zero. This is the default for a DNS (Direct Numerical Simulation), and you can set it for LES calculations that are highly resolved, like where the grid cells are a few millimeters in size. Of course, do a grid resolution study to determine if the resulting radiative fraction, i.e. {\ct -Q\_RAD/HRR}, is grid independent.


\section{Spatial and Temporal Resolution of the Radiation Transport Solver}
\label{info:RADI_Resolution}

There are several ways to improve the spatial and temporal accuracy of the discrete radiation transport equation (RTE), but each typically increases the computation time. The spatial accuracy can be improved by increasing the number of angles from the default 100 with the integer parameter {\ct NUMBER\_RADIATION\_ANGLES}. A good way to determine if you need better spatial resolution is to add slice ({\ct SLCF}) files of the quantity {\ct 'INTEGRATED INTENSITY'}. Typically, you see high values of this quantity near sources of heat, and these values decrease farther away. Ideally, you should see a somewhat smooth and circular pattern far from the heat source, but because of the finite number of solid angles along which the radiation intensity is tracked, you will see in the far field a star-like pattern that is not physical. If there are no important ``targets'' far from the heat source, this nonphysical pattern can be ignored, but if there are important targets, then increase the number of angles until you see a relatively smooth pattern over the region of interest.

The frequency of calls to the radiation solver can be changed from every 3 time steps with an integer called {\ct TIME\_STEP\_INCREMENT}. The increment over which the angles are updated can be reduced from 5 with the integer called {\ct ANGLE\_INCREMENT}. If {\ct TIME\_STEP\_INCREMENT} and {\ct ANGLE\_INCREMENT} are both set to 1, the radiation field is completely updated in a single time step, but the cost of the calculation increases significantly. By default, the radiation transport equation is fully updated every 15 time steps. Given the relatively small time steps dictated by the CFL constraint, 15 time steps is usually still a relatively short interval of time. Increasing the temporal resolution of the radiation solver rarely adds to the overall accuracy of the calculation. Spatial resolution is far more important.

If you are using multiple meshes, the radiation solver cannot transfer energy from mesh to mesh within a single time step. If you notice an obvious delay in the propagation of radiative intensity from one mesh to another, you can increase the number of times the radiative intensity is updated within a single time step using {\ct RADIATION\_ITERATIONS}, which is 1 by default. You rarely need to do this, unless it is obvious from the animation of various slice files.

The radiation solver is called before the start of the calculation to establish the radiation field in the event that you specify something to have a non-ambient temperature initially. By default, the radiation and wall boundary routines are iterated three times to establish thermal equilibrium. To change the number of iterations, set {\ct NUMBER\_INITIAL\_ITERATIONS} on the {\ct RADI} line.



\section{Other Considerations}

\paragraph{Multi-fuel radiative fraction}

If multiple fuels are present, e.g., one fuel for cardboard and one fuel for polystyrene combustion, then the radiant fraction will be computed locally as  a reaction-weighted value, similar to the approach described by Gupta et al.~\cite{Gupta:2015}. For example, if the two fuels are 20\% and 40\% radiative fraction with, respectively, 80\% and 20\% of the heat in a grid cell, $\chi_{\rm r}$ would be $0.8 \times 0.2 + 0.2 \times 0.4 = 0.24$. Thus, $\chi_{\rm r}$ will vary in space and time. The value of the multi-fuel radiative fraction can be output using the output {\ct QUANTITY} of {\ct CHI\_R}.

\paragraph{Time variation of radiative fraction}
\label{ramp_chi_r}

Even for a single fuel species the global flame radiative fraction may depend on other parameters of the problem like global equivalent ratio.  If a time variation of the radiative fraction is necessary, it may be added through a ramp function, {\ct RAMP\_CHI\_R}, on the {\ct REAC} line. The results of running the {\ct ramp\_chi\_r} test case containing the {\ct RAMP} given below is shown in Fig.~\ref{ramp_chi}.

\begin{lstlisting}
&REAC FUEL='METHANE', RADIATIVE_FRACTION=1.0, RAMP_CHI_R='CHI_R RAMP' /
&RAMP ID='CHI_R RAMP', T= 0.0, F=0.238 /
&RAMP ID='CHI_R RAMP', T= 2.0, F=0.238 /
&RAMP ID='CHI_R RAMP', T= 4.0, F=0.182 /
&RAMP ID='CHI_R RAMP', T= 6.0, F=0.158 /
&RAMP ID='CHI_R RAMP', T= 8.0, F=0.140 /
&RAMP ID='CHI_R RAMP', T= 10.0, F=0.140 /
\end{lstlisting}

\begin{figure}[h]
\begin{center}
\includegraphics[width=3in]{SCRIPT_FIGURES/ramp_chi_r}
\caption[Results of the {\ct ramp\_chi\_r} test case]{Results of the {\ct  ramp\_chi\_r} test case.}
\label{ramp_chi}
\end{center}
\end{figure}





\section{Radiative Absorption and Scattering}
\label{info:RADI_RADCAL_Absorption}

By default FDS employs a gray gas model for the radiation absorption coefficient, a function of gas composition and temperature, which are tabulated in a look-up table using the routines found in RadCal. You can output the absorption coefficient using the output {\ct QUANTITY} {\ct 'ABSORPTION COEFFICIENT'}.

\subsection{RadCal Considerations}

\label{info:RadCal}

There are several considerations with regard to RadCal:

\subsubsection{Path Length}

Because RadCal computes effective absorption coefficients over a range of wavelengths, it requires a user-specified {\ct PATH\_LENGTH} (m). Its default value is 0.1~m.

\subsubsection{Fuel Species}

\label{info:RadCal_fuelspecies}

The original version of RadCal included only absorption data for methane, which was used as a surrogate for any fuel. However, more fuel species have been added to RadCal. The current list of fuels includes: {\ct METHANE}, {\ct ETHYLENE}, {\ct ETHANE}, {\ct PROPANE}, {\ct N-HEPTANE}, {\ct METHANOL}, {\ct TOLUENE}, {\ct PROPYLENE}, and {\ct MMA}. These species are in addition to the RadCal species of: {\ct CARBON DIOXIDE}, {\ct CARBON MONOXIDE}, {\ct WATER VAPOR}, and {\ct SOOT}.



\subsection{Radiative Absorption and Scattering by Particles}

\label{info:RADI_Absorption}

The absorption and scattering of thermal radiation by Lagrangian particles is included in the radiation transport equation. The radiative properties can be given by specifying the components of the material refractive index on the corresponding {\ct PART} line, using keywords {\ct REAL\_REFRACTIVE\_INDEX} and {\ct COMPLEX\_REFRACTIVE\_INDEX}. Alternatively, wavelength dependent values of these two quantities can be tabulated in a {\ct TABLE} and called using the {\ct RADIATIVE\_PROPERTY\_TABLE}. More details can be found in Section~\ref{radiative_part_props}.

The radiative properties of the water and fuel particles (droplets) are determined automatically. For fuel, the properties of heptane are assumed. The heptane values can be overridden by specifying them on the {\ct PART} line.

Other parameters affecting the computations of particle-radiation interaction are listed here. {\ct RADTMP} is the assumed radiative source temperature. It is used in the spectral weighting during the computation of the mean scattering and absorption cross sections. The default is 900~$^\circ$C. {\ct NMIEANG} is the number of angles in the numerical integration of the Mie-phase function. Increasing {\ct NMIEANG} improves the accuracy of the radiative properties of water droplets. The cost of the better accuracy is seen in the initialization phase, not during the actual simulation. The default value for {\ct NMIEANG} is 15. For each class of particles, the Mie coefficients are calculated for a wide range of droplet diameters to ensure that the all possible run-time situations can be covered. To speed up the initialization phase, the range of diameters can be limited by parameters {\ct MIE\_MINIMUM\_DIAMETER} and {\ct MIE\_MAXIMUM\_DIAMETER}. Also, the size of the Mie coefficient tables can be specified using {\ct MIE\_NDG} parameter.

The radiation properties of most common gases involved in combustion processes (water vapor, carbon dioxide, carbon monoxide, fuel) and soot particles are automatically taken into account if the simulation involves combustion. In simulations with no combustion nor radiating species, it is possible to use a constant absorption coefficient by specifying {\ct KAPPA0} on the {\ct RADI} line.


\subsection{Wide Band Model}

\label{info:RADI_Wide_Band}

The radiation solver has two modes of operation -- a gray gas model (default) and a wide band model. Both are discussed in detail in the FDS Technical Reference Guide~\cite{FDS_Math_Guide}. If the optional six band model is desired, set {\ct WIDE\_BAND\_MODEL=.TRUE.} on the {\ct RADI} line. It is recommended that this option only be used when the fuel is relatively non-sooting because it adds significantly to the cost of the calculation.

Note also that when {\ct WIDE\_BAND\_MODEL=.TRUE.}, the output {\ct QUANTITY} {\ct 'ABSORPTION COEFFICIENT'} becomes practically useless, because it then corresponds to one individual band of the spectrum. Also, do not specify a {\ct RADIATIVE\_FRACTION} because it will not be used.

There are only a handful of fuel species known to FDS for which the band limits have been set for the six-band model. These fuels are {\ct 'ETHANE'}, {\ct 'ETHYLENE'}, {\ct 'METHANE'}, {\ct 'METHANOL'}, {\ct 'N-HEPTANE}, {\ct 'PROPANE'}, {\ct 'PROPYLENE'}, and {\ct 'TOLUENE'}.  It is possible to set your own band limits for the wide band model by specifying {\ct BAND\_LIMITS} on the {\ct RADI} line. The limits should be given in ascending order, in units of microns ($\mu$m). The maximum number of bands is 9, in which case you would specify 10 real numbers separated by commas.




\chapter{Particles and Droplets}
\label{info:PART}


Lagrangian particles can be used to represent a wide variety of objects that are too small to resolve on the numerical grid. FDS considers three major classes of Lagrangian particles: massless tracers, liquid droplets, and everything else. The parameters describing particles are found on the {\ct PART} line.



\section{Basics}
\label{info:PART_Basics}

Properties of different types of
Lagrangian particles are designated via the {\ct PART} namelist group.
Once a particular type of particle has been described using
a {\ct PART} line, then the name of that particle type is invoked
elsewhere in the input file via the parameter {\ct PART\_ID}. There are no reserved {\ct PART\_ID}s -- all must be defined.
For example, an input file may have several {\ct PART} lines that include the
properties of different types of Lagrangian particles:
\begin{lstlisting}
&PART ID='my smoke',... /
&PART ID='my water',... /
\end{lstlisting}
Particles are introduced into the calculation in several different ways: they may be introduced via a sprinkler or nozzle (liquid droplets are usually introduced this way), they may be introduced at a blowing vent or burning surface (mass tracer particles or particles representing embers are usually introduced this way), and they may be introduced randomly or at fixed points within a designated volume (solid particles that represent subgrid-scale objects are usually introduced this way). Details are found below.

The way to describe particles depends on the type.
If you simply want massless tracers, specify {\ct MASSLESS=.TRUE.} on the {\ct PART} line. If you specify a {\ct SPEC\_ID}, then FDS automatically assumes that you want relatively small, thermally-thin evaporating liquid droplets. For any other type of particle, such as particles that represent subgrid-scale objects, like office clutter or vegetation, you add a {\ct SURF\_ID} to the {\ct PART} line. All of these different types of particles are described below.


\section{Massless Particles}
\label{info:MASSLESS}

The simplest use of Lagrangian particles is for visualization, in which case the
particles are considered massless tracers. In this case, the particles are
defined via the line
\begin{lstlisting}
&PART ID='tracers', MASSLESS=.TRUE., ... /
\end{lstlisting}
Note that if the particles are {\ct MASSLESS}, it is not appropriate to color them according to any particular property. Particles are not colored by gas phase quantities, but rather by properties of the particle itself. For example, {\ct 'PARTICLE TEMPERATURE'} for a non-massless particle refers to the temperature of the particle itself rather than the local gas temperature. Also note that if {\ct MASSLESS=.TRUE.}, the {\ct SAMPLING\_FACTOR} (Section~\ref{info:part_output}) is set to 1 unless you say otherwise, which would be pointless
since {\ct MASSLESS} particles are for visualization only.

\subsection*{Turbulent Dispersion}

Massless tracer particles may also be useful in modeling dispersion of a tracer gas that does not affect the mean flow field (passive scalar).  The number density of the particles then may be translated into a local mass concentration.  See how to output number concentration in Sec.~\ref{PDPA}.  To properly account for subgrid-scale (unresolved) turbulent motions, add the parameter {\ct TURBULENT\_DISPERSION=.TRUE.} to the {\ct PART} line.  The particles will then undergo a random walk based on the subgrid diffusivity.  For further information, see the {\ct random\_walk} test cases in the {\ct WUI} directory of the verification suite.


\clearpage

\section{Liquid Droplets}

Lagrangian particles that are not just massless tracers fall into two main categories -- liquid droplets or solid particles. This section describes the former; and the next, the latter.

To define an evaporating liquid droplet, you must specify the name of the gas species created by evaporation via the {\ct SPEC\_ID} on the {\ct PART} line:
\begin{lstlisting}
&PART ID='my droplets', SPEC_ID='my gas species', ... /
\end{lstlisting}
By specifying a {\ct SPEC\_ID}, you are implicitly invoking the droplet evaporation model. Alternatively, if you specify a {\ct SURF\_ID}, you are designating a solid particle that behaves according to the given {\ct SURF} line. Solid particles are described in Section~\ref{info:PART_SURF}.


\subsection{Thermal Properties}
\label{thermal_part_props}

The properties you need to supply for a liquid droplet depend on whether or not the {\ct SPEC\_ID} is listed in Table~\ref{tab:gasspecies}, and if the column labelled ``Liquid'' is checked with a ``Y'', meaning that its liquid properties are known. The following sub-sections provide instructions on what to do in various instances. Note that the {\ct INITIAL\_TEMPERATURE} ($^\circ$C) of the liquid droplets is specified on the {\ct PART} line. Its default value is the overall ambient temperature of the simulation, {\ct TMPA}, from the {\ct MISC} line.

\subsubsection{Known Liquid/Gas Species}

If the {\ct SPEC\_ID} is listed in Table~\ref{tab:gasspecies}, and if the column labelled ``Liquid'' is checked with a ``Y'', you need only list the following:
\begin{lstlisting}
&SPEC ID='WATER VAPOR' /
&PART ID='water droplets', SPEC_ID='WATER VAPOR', ... /
\end{lstlisting}
There might be other optional parameters listed on the {\ct PART} line, but these are the ones that are absolutely necessary. In addition, if {\ct SPEC\_ID='WATER VAPOR'} the droplets are not only assigned the thermo-physical properties of water, but also the radiation absorption properties are set to that of water, and the droplets are colored blue in Smokeview.

\subsubsection{Unknown Liquid/Gas Species}

If the {\ct SPEC\_ID} is not listed in Table~\ref{tab:gasspecies} with a ``Y'' in the ``Liquid'' column, you must provide all of the following properties of the liquid on the {\ct SPEC} line:
\begin{description}
\item[{\ct DENSITY\_LIQUID}] (kg/m$^3$).
\item[{\ct SPECIFIC\_HEAT\_LIQUID}] (\si{kJ/(kg.K})). If the specific heat of the liquid is a function of temperature, use {\ct RAMP\_CP\_L} to provide the function $c_p(T)$.
\item[{\ct VAPORIZATION\_TEMPERATURE}] Boiling temperature of the liquid, $T_{\rm boil}$ ($^\circ$C).
\item[{\ct MELTING\_TEMPERATURE}] Melting (solidification) temperature of the liquid ($^\circ$C).
\item[{\ct ENTHALPY\_OF\_FORMATION}] The heat of formation of the gas (kJ/mol).
\item[{\ct HEAT\_OF\_VAPORIZATION}] Latent heat of vaporization of the liquid, $h_{\rm v}$ (kJ/kg).
\item[{\ct H\_V\_REFERENCE\_TEMPERATURE}] The temperature corresponding to the {\ct HEAT\_OF\_VAPORIZATION} ($^\circ$C).
\end{description}
Note that FDS will adjust the liquid enthalpy so that the following relationship holds:
\be
   h_{\rm gas}(T_{\rm boil}) = h_{\rm liquid}(T_{\rm boil}) + h_{\rm v}
\ee


\subsubsection{Fuel Liquid/Gas Species}
\label{info:fuel_droplets}
\label{spray_burner}

If the liquid droplets burn, the {\ct SPEC\_ID} on the {\ct PART} line should designate the {\ct FUEL} on the {\ct REAC} line. Depending on the combustion model, you may not need to create a separate {\ct SPEC} line. Fuel droplets will be colored yellow by default in Smokeview and any resulting fuel vapor will burn according to the combustion model specified on the {\ct REAC} line. The droplets evaporate into an equivalent amount of fuel vapor such that the resulting heat release rate (assuming complete combustion) is equal to the evaporation rate multiplied by the {\ct HEAT\_OF\_COMBUSTION}. The {\ct HEAT\_OF\_COMBUSTION} can be specified on the {\ct PART} line, or the {\ct REAC} line, or it will be calculated automatically by FDS. If it is specified on the {\ct PART} line, the burning rate will be adjusted to account for the difference between the heats of combustion of this particular droplet and the other fuels in the model. If you let FDS calculate the heat of combustion automatically, run the model for a few time steps and look for the ``Heat of Combustion'' listed in the {\ct CHID.out} file. Use this value to specify the flow rate from the nozzle to achieve your desired heat release rate.

If a spray nozzle is used to generate the fuel droplets, its characteristics are specified in the same way as those for a sprinkler.  If the fuel species is listed in Table~\ref{tab:gasspecies} and the column labelled ``RadCal Surrogate'' is not blank, then the droplets will be assigned fuel radiation absorption properties corresponding to the listed species.

Note that to limit the computational cost of sprinkler simulations, liquid droplets disappear when they hit the ``floor'' of the computational domain, regardless of whether it is solid or not. However, this may not be desired when using liquid fuels. To stop FDS from removing liquid droplets from the floor of the domain, add the phrase {\ct POROUS\_FLOOR=.FALSE.} to the {\ct MISC} line. An alternate solution is make sure the {\ct OBST} the fuel is landing on is at least one cell thick.

In the example file ({\ct Fires/spray\_burner.fds}), heptane from two nozzles is sprayed downwards into a steel pan.  The flow rate is increased linearly so that the fire grows to 2~MW in 20 s, burns steadily for another 20 s, and then ramps down linearly in 20 s. The key input parameters are given here:
\begin{lstlisting}
&REAC FUEL='N-HEPTANE',SOOT_YIELD=0.01 /

&DEVC ID='nozzle_1', XYZ=4.0,-.3,0.5, PROP_ID='nozzle', QUANTITY='TIME', SETPOINT=0. /
&DEVC ID='nozzle_2', XYZ=4.0,0.3,0.5, PROP_ID='nozzle', QUANTITY='TIME', SETPOINT=0. /

&PART ID='heptane droplets', SPEC_ID='N-HEPTANE',
      QUANTITIES(1:2)='PARTICLE DIAMETER','PARTICLE TEMPERATURE',
      DIAMETER=1000., SAMPLING_FACTOR=1 /

&PROP ID='nozzle', PART_ID='heptane droplets',  HEAT_OF_COMBUSTION=44500.,
      FLOW_RATE=1.97, FLOW_RAMP='fuel', PARTICLE_VELOCITY=10.,
      SPRAY_ANGLE=0.,30., SMOKEVIEW_ID='nozzle' /
&RAMP ID='fuel', T= 0.0, F=0.0  /
&RAMP ID='fuel', T=20.0, F=1.0  /
&RAMP ID='fuel', T=40.0, F=1.0  /
&RAMP ID='fuel', T=60.0, F=0.0  /
\end{lstlisting}
Many of these parameters are self-explanatory. Note that a 2~MW fire is achieved via 2 nozzles flowing heptane at 1.96~L/min each:
\be
   2 \times 1.97 \; \frac{\hbox{L}}{\hbox{min}} \times \frac{1}{60} \; \frac{\hbox{min}}{\hbox{s}} \times 684 \;
   \frac{\hbox{kg}}{\hbox{m}^3} \times \frac{1}{1000} \; \frac{\hbox{m}^3}{\hbox{L}} \times 44500 \;
   \frac{\hbox{kJ}}{\hbox{kg}} = 2000 \; \hbox{kW}
\ee
The parameter {\ct HEAT\_OF\_COMBUSTION} over-rides that for the overall reaction scheme. Thus, if other droplets or solid objects have different heats of combustion, the effective burning rates are adjusted so that the total heat release rate is that which you expect. However, exercises like this ought to be conducted just to ensure that this is the case. The HRR curve for this example is given in Fig.~\ref{spray_burner_fig}.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=3.5in]{SCRIPT_FIGURES/spray_burner_HRR}
\end{center}
\caption[Results of the {\ct spray\_burner} test case]{Heat Release Rate (HRR) of spray burner test.}
\label{spray_burner_fig}
\end{figure}

Note also that this feature is subject to mesh dependence. If the mesh cells are too coarse, the evaporating fuel can be diluted to such a degree that it may not burn. Proper resolution depends on the type of fuel and the amount of fuel being ejected from the nozzle. Always test your burner at the resolution of your overall simulation.


\subsection{Radiative Properties}
\label{radiative_part_props}

The radiative properties of water and fuel droplets are determined automatically. For fuel, the properties of heptane are assumed. For other types of particles, the radiative properties can be given by specifying the components of the material refractive index on the corresponding {\ct PART} line, using keywords {\ct REAL\_REFRACTIVE\_INDEX} and {\ct COMPLEX\_REFRACTIVE\_INDEX}. Alternatively, wavelength dependent values of these two quantities can be specified using a spectral property table ({\ct TABL}) whose {\ct ID} is indicated on the {\ct PART} line via {\ct RADIATIVE\_PROPERTY\_TABLE}. Each row of a spectral property table contains three real numbers: wavelength ($\mu$m), and the real and complex components of the refractive index. The real part of the refractive index should be a positive number. If it is greater than 10, the particles are treated as perfectly reflecting spheres. The complex part should be a non-negative number. Values less than $10^{-6}$ are treated as non-absorbing. Below is an example of the use of the spectral property table, listing the properties at wavelengths 1, 5 and 10 $\mu$m.
\begin{lstlisting}
&PART ID='my particles',..., RADIATIVE_PROPERTY_TABLE='radtab' /
&TABL ID='radtab', TABLE_DATA= 1.0,1.33,0.0001 /
&TABL ID='radtab', TABLE_DATA= 5.0,1.33,0.002  /
&TABL ID='radtab', TABLE_DATA=10.0,1.33,0.001  /
\end{lstlisting}
For calculating the absorption of thermal radiation by particles, FDS uses a running average of particle temperature and density. The {\ct RUNNING\_AVERAGE\_FACTOR} is set on the {\ct PART} line, and its default value is 0.5 for liquid droplets and 0 for solid particles. The value of 0 indicates that no running average is used.


\subsection{Size Distribution}
\label{info:particle_size}
\label{droplet_distributions_2}

The size distribution of liquid droplets is specified using a cumulative volume fraction (CVF)\footnote{The CVF indicates the fraction of total mass carried by droplets less than the given diameter.} indicated by the character string {\ct DISTRIBUTION} on the {\ct PART} line. The default is \linebreak[3] {\ct 'ROSIN-RAMMLER-LOGNORMAL'}:
\be F(D) = \left\{
   \begin{array}{ll}
   \frac{1}{\sqrt{2\pi}} {\displaystyle \int_0^D} \, \frac{1}{\sigma\, D'} \,
   \exp \left( -\frac{[\ln(D'/D_{\rm v,0.5})]^2}{2\sigma^2} \right) \; \d D'       & (D \le D_{\rm v,0.5}) \\ [0.2in]
   1 - \exp \left( -0.693 \left(\frac{D}{D_{\rm v,0.5}}\right)^\gamma \right)      & (D > D_{\rm v,0.5})
   \end{array} \right.
\ee
Alternatively, you can specify {\ct 'LOGNORMAL'} or {\ct 'ROSIN-RAMMLER'} alone rather than the combination of the two. Figure~\ref{droplet_distributions} displays the possible size distributions. Notice that the {\ct 'LOGNORMAL'} and \linebreak[4]{\ct 'ROSIN-RAMMLER'} distributions have undesirable attributes at opposite tails, which is why the combination of the two is commonly used. Figure~\ref{droplet_distributions} also shows a comparison between the prescribed distribution and the actual realized distribution of droplet sizes. The dashed lines show the measured droplet size distributions, while the solid lines show the prescribed sampling distributions. The sampled distributions are measured with the {\ct PDPA\_HISTOGRAM} function. Sample size of 10000 droplets was used.

The median volumetric diameter, $D_{\rm v,0.5}$, is specified via the parameter {\ct DIAMETER} ($\mu$m) on the {\ct PART} line. You must specify the {\ct DIAMETER} in cases where the droplets evaporate (in which case you also need to specify a {\ct SPEC\_ID} to indicate the gas species generated by the evaporating droplets). The width of the lognormal distribution, $\sigma$, is specified with {\ct SIGMA\_D} on the {\ct PART} line. The width of the Rosin-Rammler distribution, $\gamma$, is specified with {\ct GAMMA\_D} (default 2.4). Note that in the combined distribution, the parameter, $\sigma$, is calculated $\sigma=2/(\sqrt{2\pi} \, (\ln\,2) \; \gamma)=1.15/\gamma$ which ensures that the two functions are smoothly joined at $D = D_{\rm v,0.5}$. You can also add a value for {\ct SIGMA\_D} to the {\ct PART} line if you want to over-ride this feature. The larger the value of $\gamma$, the narrower the droplet size is
distributed about the median value.

\begin{figure}[ht]
\begin{tabular}{ll}
\includegraphics[height=2.2in]{SCRIPT_FIGURES/droplet_distributions_1} &
\includegraphics[height=2.2in]{SCRIPT_FIGURES/droplet_distributions_2} \\
\includegraphics[height=2.2in]{SCRIPT_FIGURES/droplet_distributions_3} &
\includegraphics[height=2.2in]{SCRIPT_FIGURES/droplet_distributions_4}
\end{tabular}
\caption[Droplet size distributions]{Droplet size distributions. The first three plots are based on a specified CVF from which the CNF is derived. The fourth plot (lower right) is an example of a specified CNF from which the CVF is derived. CVF:s are plotted with black lines, while CNF:s are plotted with red lines. The solid lines show the prescribed sampling distribution, while the dashed lines show the actual sampled droplet size distribution, measured with the {\ct PDPA\_HISTOGRAM} functionality.}
\label{droplet_distributions}
\end{figure}


You can specify your own cumulative number fraction (CNF)\footnote{The CNF indicates the fraction of total droplets whose diameters are less than the given diameter.} by specifying a {\ct CNF\_RAMP\_ID} on the {\ct PART} line and including a {\ct RAMP} that gives the CNF:
\begin{lstlisting}
&PART ID='my droplets',..., CNF_RAMP_ID='my CNF' /
&RAMP ID='my CNF', T=   0., F=0.000000 /
&RAMP ID='my CNF', T= 200., F=0.000003 /
...
&RAMP ID='my CNF', T=2000., F=1.000000 /
\end{lstlisting}
Note that the {\ct RAMP} variable {\ct T} indicates the diameter and is given in micrometers. The fourth plot in Fig.~\ref{droplet_distributions} is an example of where the CNF is specified and the CVF is calculated from it. It is essentially the reverse of what is shown in the first plot, where the CVF is specified and the CNF is calculated from it.

As droplets are created in the simulation, their diameters are randomly chosen based on the given distribution. You can prevent excessively large droplets from being chosen by specifying a {\ct MAXIMUM\_DIAMETER}, which is assigned an infinitely large value by default. Droplets less than a specified {\ct MINIMUM\_DIAMETER} are assumed to evaporate in a single time step. The default value is 0.005 times the value of {\ct DIAMETER}. The droplet diameter range is divided into a series of bins\footnote{By default, the range of particle sizes is divided into six bins, and the sampled particles are divided among these bins. This ensures that a reasonable number of particles are assigned to the entire spectrum of sizes. To change the default number of bins, set {\ct N\_STRATA} on the {\ct PART} line.}. To avoid very small particle weights, the distribution is clipped at the cumulative fractions of {\ct CNF\_CUTOFF} and (1 - {\ct CNF\_CUTOFF}).  Note that {\ct CNF\_CUTOFF} is set on the {\ct MISC} line. The default value of {\ct CNF\_CUTOFF} is 0.005.

To prevent FDS from generating a distribution of droplets altogether, set {\ct MONODISPERSE} to {\ct .TRUE.} on the {\ct PART} line, in which case every droplet will be assigned the same {\ct DIAMETER}.

If you set {\ct CHECK\_DISTRIBUTION=.TRUE.} on the {\ct PART} line, FDS will write out the cumulative distribution function for that particular particle class in a file called {\ct CHID\_PART\_ID\_cdf.csv}. If you do this, you might want to avoid spaces in the {\ct ID} of the {\ct PART} line.




\subsection{Secondary Breakup}
\label{info:secondary_breakup}

If {\ct BREAKUP=.TRUE.} is set on the {\ct PART} line, particles may undergo secondary breakup.
In this case you should also specify the {\ct SURFACE\_TENSION} (N/m) of the liquid and the resulting ratio of the median volumetric diameter, $D_{\rm v,0.5}$, {\ct BREAKUP\_RATIO}. Its default is 3/7. Optionally, specify the distribution parameters \linebreak[4]{\ct BREAKUP\_GAMMA\_D} and {\ct BREAKUP\_SIGMA\_D}. These parameters are defined the same as {\ct GAMMA\_D} and {\ct SIGMA\_D} in section~\ref{info:particle_size} but instead apply after breakup.

\subsection{Dense Clouds of Droplets}
\label{info:DENSE_VOLUME_FRACTION}

If the local liquid droplet density is relatively high, as at a sprinkler or hose nozzle, the drag on individual droplets is reduced by wake effects. FDS includes a sub-model that accounts for drag reduction due to wake effects. This model is invoked if the local liquid volume fraction is greater than a threshold value called {\ct DENSE\_VOLUME\_FRACTION}, a parameter that is set on the {\ct PART} line. Setting this parameter to a relatively large number (1 is sufficient) turns off the wake reduction model. Its default value is $1\times 10^{-5}$.


\clearpage

\section{Solid Particles}
\label{info:PART_SURF}

Lagrangian particles can represent a wide variety of subgrid-scale objects, from office clutter to vegetation. To create solid, non-liquid particles, you must add a {\ct SURF\_ID} to the {\ct PART} line. The specified {\ct SURF} line contains the parameters that describe the thermophysical properties and geometric parameters of the particle. These properties are the same as those you would apply to an {\ct OBST} or {\ct VENT}. FDS uses the same solid phase conduction and pyrolysis algorithm for particles as it does for solid walls.

If the {\ct SURF} line that is associated with the particle class calls for it, the particles will heat up due to convection from the surrounding gases and radiation from near and distant sources. The convective heat transfer coefficient takes into account the particle geometry, and the radiative heat flux is based on the integrated intensity. That is, the radiation heat flux is the average over all angles. However, you can specify unique directions for the particle if the source of heating does not surround the particles. More about particle splitting is explained in Section~\ref{info:particle_split}.


\subsection{Basic Geometry and Boundary Conditions}
\label{info:PART_GEOMETRY}

To demonstrate the basic syntax for solid particles, the following input lines create a collection of hot spheres:
\begin{lstlisting}
&PART ID='spheres', SURF_ID='HOT', STATIC=.TRUE., PROP_ID='ball' /
&SURF ID='HOT', TMP_FRONT=500., RADIUS=0.005, GEOMETRY='SPHERICAL' /
&PROP ID='ball', SMOKEVIEW_ID='SPHERE', SMOKEVIEW_PARAMETERS(1)='D=0.01' /
&INIT PART_ID='spheres', XB=0.25,0.75,0.25,0.75,0.25,0.75, N_PARTICLES=10 /
\end{lstlisting}
The {\ct PART} line establishes the class of particles. In this case, the presence of a {\ct SURF\_ID} indicates that the particles are solids with the properties given by the {\ct SURF} line {\ct 'HOT'}. {\ct STATIC} is a logical parameter whose default is {\ct .FALSE.} that indicates if the particles are stationary. The {\ct PROP\_ID} references a {\ct PROP} (property) line that just tells Smokeview that the particles are to be drawn as spheres of diameter 0.01~m. See Section~\ref{info:SMOKEVIEW_PART} for details and options. The {\ct INIT} line randomly fills the given volume with 10 of these hot spheres. See Section~\ref{info:initial_droplets} for details.

If the {\ct SURF} line includes a {\ct MATL\_ID}, the particle mass will be based upon the value(s) of {\ct DENSITY} of the referenced {\ct MATL} line(s). If there is to be no heat conduction calculation in depth, do not specify a {\ct MATL\_ID}. Instead, you can specify, for example, the surface temperature, {\ct TMP\_FRONT} ($^\circ$C), heat release rate per unit area, {\ct HRRPUA} (kW/m$^2$), or species {\ct MASS\_FLUX} (\si{kg/(m$^2$.s)}).

The {\ct GEOMETRY} options for solid particles are {\ct 'SPHERICAL'}, {\ct 'CYLINDRICAL'}, or {\ct 'CARTESIAN'}.
By default, the {\ct GEOMETRY} is {\ct 'CARTESIAN'}, in which case you need to provide the {\ct LENGTH} and {\ct WIDTH} of the rectangular plate. It is assumed that the plate is symmetric front and back (note this means you should set {\ct BACKING='INSULATED'} on the {\ct SURF} line). You need only specify the layers that make up the half-thickness. The array {\ct THICKNESS(N)} indicates the thickness(es) of each layer of the plate, not the total thickness of the plate itself. If the plate is composed of only one material component, the specified {\ct THICKNESS} is taken as the half-thickness of the plate.

For  {\ct 'CYLINDRICAL'} or {\ct 'SPHERICAL'} particles, specify the {\ct INNER\_RADIUS} and {\ct THICKNESS} of the individual layers. Alternatively, you can just specify the {\ct RADIUS} if the cylinder or sphere is solid and has only one material component. The default value of {\ct INNER\_RADIUS} is 0~m, which means that the radius of the cylinder or sphere is the sum of the {\ct THICKNESS} values. Remember that the layers are to be listed starting at the surface, not the center. For {\ct 'CYLINDRICAL'} particles, specify a {\ct LENGTH} as well.

\subsubsection{Particles with Periodic Boundary Conditions}
\label{info:periodic-particles}

By default, particles are not recycled at a periodic boundary. To recycle the particles in the $x$-direction, set {\ct PERIODIC\_X=.TRUE.} on the {\ct PART} line. Set {\ct PERIODIC\_Y=.TRUE.} and {\ct PERIODIC\_Z=.TRUE.} for the $y$- and $z$-directions, respectively.


\subsection{Drag}
\label{info:particle_drag}

The drag force exerted by moving or stationary particles is detailed in the FDS Technical Reference Guide, chapter ``Lagrangian Particles''~\cite{FDS_Math_Guide}. For solid particles, the default drag law is that of a solitary sphere. To invoke a different drag law, that of a solitary cylinder for example, set {\ct DRAG\_LAW = 'CYLINDER'} on the {\ct PART} line. A summary of the available drag laws is given in table~\ref{tbl:draglaws}. If none of these options is applicable, you may specify a constant value of the drag coefficient for a particle class (a specific {\ct PART\_ID}) by setting a {\ct DRAG\_COEFFICIENT} on the {\ct PART} line. The {\ct DRAG\_COEFFICIENT} over-rides the {\ct DRAG\_LAW}.

\begin{table}[ht]
\begin{center}
\caption{Drag laws available in FDS}
\label{tbl:draglaws}
\begin{tabular}{|c|c|}
\hline
{\ct DRAG\_LAW}           & Reference   \\ \hline\hline
{\ct 'SPHERE'} (default)  & FDS Tech Guide \cite{FDS_Math_Guide}   \\ \hline
{\ct 'CYLINDER'}          & FDS Tech Guide \cite{FDS_Math_Guide}   \\ \hline
{\ct 'POROUS MEDIA'}      & Sec.~\ref{info:porous_media}           \\ \hline
{\ct 'SCREEN'}            & Sec.~\ref{info:particle_screen}        \\ \hline
\end{tabular}
\end{center}
\end{table}

If you are modeling a relatively dense collection of solid particles, like vegetation, you should set the {\ct DRAG\_COEFFICIENT} explicitly and not rely on the correlations for spheres and cylinders which were developed for relatively independent bodies, not clusters.


\subsection{Radiation Absorption and Emission}
\label{info:particle_radiation_absorption}

The absorption and emission of thermal radiation by a group of solid particles is controlled by the absorption coefficient:
\be
   \kappa_{\rm p} = \frac{\sum C_{\rm s} \, A_{\rm p,s}}{V}
\ee
where $C_{\rm s}$ is the shape factor (ratio of cross sectional area to surface area) of the class of particles, $A_{\rm p,s}$ is the surface area of the particle, and $V$ is the volume of the grid cell. You can specify the {\ct SHAPE\_FACTOR} of a class of particles on the {\ct PART} line. The default value is that of a sphere, 0.25.



\subsection{Splitting Particles}
\label{info:particle_split}

If the radiation heat flux is not uniformly distributed about the particle, it may be useful to split the particle into pieces, each with its own orientation. This can be done by using the parameter {\ct ORIENTATION} to specify  more than one outward facing directions for the particle. For example,
\begin{lstlisting}
&PART ..., ORIENTATION(1:3,1)=0,0,-1, ORIENTATION(1:3,2)=0,0,1 /
\end{lstlisting}
specifies that half the particle is facing downwards and half is facing upwards. FDS now essentially tracks two particles. The radiative flux to the downward facing particle is the integrated average over the southern hemisphere; the flux to the upward facing particle is the average over the northern hemisphere. The particle mass and the surface area are scaled by the number of orientations. The splitting along the coordinate axis is demonstrated for all geometries in Fig.~\ref{part_split}. The orientation direction does not have to align with the coordinate axes. In fact, the {\ct ORIENTATION}s do not have to be symmetric or come in pairs, even though for most applications it makes sense to do it this way. For a Cartesian particle (i.e., a plate), only the orientations that are perpendicular to the plate make physical sense. Keep in mind that the heat conducted within the different facets does not transfer through to the other facets. The heat conduction is still only one dimensional, in the direction normal to the face and towards the center.

\begin{figure}[p]
\begin{center}
\includegraphics[height=2.0in]{FIGURES/FDS_User_Guide_Cartesian_Particle_Drawing}

\vspace{0.5in}

\includegraphics[height=2.8in]{FIGURES/FDS_User_Guide_Cylindrical_Particle_Drawing}

\vspace{0.5in}

\includegraphics[height=2.5in]{FIGURES/FDS_User_Guide_Sphere_Particle_Drawing}
\end{center}
\caption[Examples of particle splitting]{Examples of a Cartesian (plate), cylindrical, and spherical particle split into multiple parts.}
\label{part_split}
\end{figure}

Note that if only a single {\ct ORIENTATION} vector is assigned on a {\ct PART} line, the radiative flux to the particle is calculated as if there is a flat plate normal to the direction of the vector, like a conventional heat flux gauge. That is, the heat flux is not an integrated average over the entire particle but rather the directional heat flux with the given orientation. The reason for this exception to the general rule is that often single particles are used as ``targets'' to record a heat flux at a given point in the domain with a given orientation. These particles can be thought of as tiny heat flux gauges that do not disturb the flow.

\subsection{Gas Generating Particles}
\label{info:particle_mass_generation}
\label{surf_mass_part_specified}

Lagrangian particles can be used to generate gases at a specified rate. The syntax is similar to that used for a solid wall. For example, the following input lines create three particles -- one shaped like a rectangular plate, one a cylinder, and one a sphere -- that generate argon, sulfur dioxide, and helium, respectively. The particles have no mass; they simply are used to generate the gases at a specified rate.
\begin{lstlisting}
&SPEC ID='ARGON' /
&SPEC ID='SULFUR DIOXIDE' /
&SPEC ID='HELIUM' /

&INIT PART_ID='plate', XYZ=-1.,0.,1.5, N_PARTICLES=1  /
&INIT PART_ID='tube',  XYZ= 0.,0.,1.5, N_PARTICLES=1  /
&INIT PART_ID='ball',  XYZ= 1.,0.,1.5, N_PARTICLES=1  /

&PART ID='plate', SAMPLING_FACTOR=1, SURF_ID='plate bc', STATIC=.TRUE. /
&PART ID='tube',  SAMPLING_FACTOR=1, SURF_ID='tube bc',  STATIC=.TRUE. /
&PART ID='ball',  SAMPLING_FACTOR=1, SURF_ID='ball bc',  STATIC=.TRUE. /

&SURF ID='plate bc', THICKNESS=0.001, LENGTH=0.05, WIDTH=0.05, SPEC_ID(1)='ARGON',
      MASS_FLUX(1)=0.1, TAU_MF(1)=0.001 /
&SURF ID='tube bc',  GEOMETRY='CYLINDRICAL', LENGTH=0.05, RADIUS=0.01,
      SPEC_ID(1)='SULFUR DIOXIDE', MASS_FLUX(1)=0.1, TAU_MF(1)=0.001 /
&SURF ID='ball bc',  GEOMETRY='SPHERICAL', RADIUS=0.01, SPEC_ID(1)='HELIUM',
      MASS_FLUX(1)=0.1, TAU_MF(1)=0.001 /
\end{lstlisting}
In this case, there is no calculation of heat conduction in depth. Only the surface area is important. For the plate, the surface area is twice the length times the width. For the cylinder, the area is twice the radius times $\pi$ times the length. For the sphere, the area is $4\pi$ times the radius squared. Figure~\ref{surf_mass_part_specified_fig} displays the output of the test case called {\ct surf\_mass\_part\_specified.fds}, demonstrating that the production rate of the gases is as expected.

\begin{figure}[ht]
\begin{center}
\includegraphics[height=2.2in]{SCRIPT_FIGURES/surf_mass_part_specified}
\end{center}
\caption[Example of specified gas mass production from particles]{Gas production from three Lagrangian particles.}
\label{surf_mass_part_specified_fig}
\end{figure}



\subsection{Vegetation}
\label{info:vegetation}
\label{pine_needles}

Lagrangian particles can be used to represent different types of vegetation, like leaves, grass, and so on. The best way to explain how to use this feature is by way of example. Suppose we want to describe a collection of wet pine needles that occupy a certain volume. The following lines have been extracted from the sample file {\ct WUI/pine\_needles.fds}. Note that all of the values have been chosen simply to demonstrate the technique. These values should not be used for a real calculation.
\begin{lstlisting}
&PART ID='pine needles', SAMPLING_FACTOR=1, SURF_ID='wet vegetation',
      PROP_ID='needle image', STATIC=.TRUE. /
&INIT PART_ID='pine needles', XB=0.,1.,0.,1.,0.,1., N_PARTICLES=1000,
      MASS_PER_VOLUME=1. /
&PROP ID='needle image', SMOKEVIEW_ID='TUBE',
      SMOKEVIEW_PARAMETERS='L=0.1','D=0.0005' /

&SURF ID = 'wet vegetation'
      MATL_ID(1,1:2) = 'PINE','MOISTURE'
      MATL_MASS_FRACTION(1,1:2) = 0.8,0.2
      THICKNESS = 0.00025
      LENGTH = 0.1
      GEOMETRY = 'CYLINDRICAL' /

&MATL ID = 'PINE'
      DENSITY = 500.
      CONDUCTIVITY = 0.1
      SPECIFIC_HEAT = 1.0
      N_REACTIONS = 1
      REFERENCE_TEMPERATURE = 300.
      NU_MATL = 0.2
      NU_SPEC = 0.8
      SPEC_ID = 'GLUCOSE'
      HEAT_OF_REACTION = 1000
      MATL_ID  = 'CHAR' /

&MATL ID = 'MOISTURE'
      DENSITY = 1000.
      CONDUCTIVITY = 0.1
      SPECIFIC_HEAT = 4.184
      N_REACTIONS = 1
      REFERENCE_TEMPERATURE = 100.
      NU_SPEC = 1.0
      SPEC_ID = 'WATER VAPOR'
      HEAT_OF_REACTION = 2500. /

&MATL ID = 'CHAR'
      DENSITY = 200.
      CONDUCTIVITY = 1.0
      SPECIFIC_HEAT = 1.6 /
\end{lstlisting}
In the example, 1~kg of pine needles occupy 1~m$^3$. The number of particles used to represent the pine needles is somewhat arbitrary. FDS will automatically weight the specified number so that the total mass per volume is 1~kg. The needles are modeled as cylinders that are 0.5~mm in diameter. The {\ct THICKNESS} on the {\ct SURF} line refers to the radius of the cylinder in units of m. The needles are all 0.1~m long. The needles contain 20~\% (by mass) moisture, and 80~\% cellulose. The moisture is set to evaporate at 100~$^\circ$C to create water vapor and the cellulose pyrolyzes at 300~$^\circ$C to form fuel gas and char. In the example case, the original 1~kg of vegetation is heated until all of the water and fuel evaporate. The fuel is not allowed to burn by setting the ambient oxygen concentration to 1~\%. Figure~\ref{pine_needles_fig} shows the evolution of the fuel, water and char mass. Agreement with the expected values means that mass is conserved.

\begin{figure}[ht]
\begin{center}
\includegraphics[height=2.2in]{SCRIPT_FIGURES/pine_needles}
\end{center}
\caption[Example of burning vegetation]{Evolution of vegetation mass in the {\ct pine\_needles} test case.}
\label{pine_needles_fig}
\end{figure}

\subsubsection{Notation used in Forestry}

Users of FDS that work in wildland fire or forestry may be unfamiliar with some of the vegetation material properties in FDS input files. Specifically, the thickness and length of needles or roundwood, for a given vegetation type, are not routinely reported (the surface-to-volume ratio is reported instead). Also, while the bulk density is reported (or can be easily found from vegetation loading and height), it is based on the dry mass. Moisture content is reported on a dry weight basis, $M_{\rm dw}$. The {\ct MASS\_FRACTION} of moisture on the {\ct SURF} line is $M_{\rm dw} / (1 + M_{\rm dw})$. In addition, the surface-to-volume ratio of the vegetation, $\sigma_{\rm v}$, is reported instead of the physical dimensions. If we assume a cylindrical shape, with the length of the cylinder being much larger than the radius, then the radius of the cylinder (input as {\ct THICKNESS}) is $2/\sigma_{\rm v}$. The {\ct MASS\_PER\_VOLUME} is equivalent to $m_{\rm d}''' \, (1+M_{\rm dw})$ where $m_{\rm d}'''$ is the mass per unit volume of dry vegetation.


\subsection{Firebrands}
\label{info:firebrands}
\label{dragon_5a}

Firebrands are small pieces of burning wood and vegetation that can be lofted into the air and blown by the wind ahead of a wildland fire front. Manzello et~al.~\cite{Manzello:FSJ2008a} have developed a variety of experimental apparatus designed to generate firebrands in a laboratory setting. The example input file called {\ct dragon\_5a} in the {\ct WUI} (Wildland-Urban Interface) folder is a very simple mock-up of one of these experiments. The word ``dragon'' is based on the nickname of the apparatus; 5a is the figure number in Ref.~\cite{Manzello:FSJ2008a} on which this example case is loosely based. In the experiment, 700~g of small dowels (length 50~mm, diameter 8~mm) made of Ponderosa Pine wood were poured into a small steel chamber equipped with several propane burners. The dowels were left to burn for roughly a minute subject to a slow induced air flow after which time the air flow was increased and firebrands were propelled horizontally out of a 15~cm duct 2.25~m above the lab floor. It is reported that after several replicate experiments, the average mass of the firebrands collected from pans on the floor was 57~g. The average diameter of the collected dowels was 5.6~mm, and the average length was 13.5~mm.

It is not possible to simulate the experiment in FDS exactly as it was performed. The reason is that in the experiment, all 700~g of the wooden dowels were poured into the heating chamber at once. FDS cannot handle such a dense packing of Lagrangian particles. Instead, the simulated dowels are introduced at a rate of 10 per second. FDS also does not have a mechanism to break-up the dowels, reducing their length from 50~mm to 13.5~mm. Thus, the initial cylindrical particles are 13.5~mm and remain that length throughout the simulation. The diameter of the cylindrical particles is reduced, however, from 8~mm to 5.6~mm, which takes the initial density of 440~kg/m$^3$ down to 71~kg/m$^3$ because the mass of the firebrands is assumed to be 8~\% of the original. The plot in Fig.~\ref{dragon_5a_fig} shows the increasing mass of firebrands thrown to the floor in the simulation after 100~s of particle insertion. The total mass of particles inserted into the apparatus is:
\be \pi \, (0.004 \; {\rm m})^2 \times (0.0135 \; {\rm m}) \times (440 \; {\rm kg/m}^3) \times (10 \; {\rm part/s}) \times (100 \; {\rm s}) \approx 0.3 \; {\rm kg} \ee
The amount expected on the floor is approximately 0.024~kg.

\begin{figure}[ht]
\begin{center}
\includegraphics[height=2.2in]{SCRIPT_FIGURES/dragon_5a}
\end{center}
\caption[Mass generation of firebrands in the {\ct dragon\_5a} test case]{Mass generation of firebrands in the {\ct dragon\_5a} test case.}
\label{dragon_5a_fig}
\end{figure}

\subsection{Porous Media}
\label{info:porous_media}

A 3-D array of particles can be used to represent the drag exerted by porous media, as in the following example:
\begin{lstlisting}
&SURF ID='LIGAMENT', MATL_ID='ALUMINUM ALLOY', THICKNESS=7.3E-5,
      GEOMETRY='CYLINDRICAL', HEAT_TRANSFER_COEFFICIENT=10. /
&MATL ID='ALUMINUM ALLOY', DENSITY=2690., CONDUCTIVITY=218., SPECIFIC_HEAT=0.9 /
&PART ID='FOAM', DRAG_LAW='POROUS MEDIA', SURF_ID='LIGAMENT',
      POROUS_VOLUME_FRACTION=0.12, STATIC=.TRUE.,
      DRAG_COEFFICIENT=0.1,0.1,0.1, PERMEABILITY=1.0E-7,1.E-7,1.E-7 /
&INIT XB=1.010,1.095,0.0,0.5,0.0,0.5, N_PARTICLES_PER_CELL=1, CELL_CENTERED=.TRUE.,
      PART_ID='FOAM' /
\end{lstlisting}
These lines are a model of aluminum foam. The basic geometry of the foam ligaments is defined with the {\ct SURF} line. It is assumed that the ligaments are made of an aluminum alloy whose properties are given on the {\ct MATL} line. The radius of the assumed cylindrical ligament is indicated by the {\ct THICKNESS}. Note that the {\ct LENGTH} of the cylinder which is normally required on the {\ct SURF} line is computed automatically so that the volume fraction of the grid cell occupied by the foam, specified by {\ct POROUS\_VOLUME\_FRACTION} on the {\ct PART} line, is achieved. In a sense, the foam is modeled by a long cylinder chopped up into small pieces and represented by a single particle in each grid cell.

The {\ct PART} line provides information about the particles. The {\ct DRAG\_LAW} indicates a special empirical model for the porous media. This model states that the pressure drop through the media is given by
\be
   \label{eqn_porous_media}
   \Delta p =  \delta \, \left(\frac{\mu}{K} u + \rho \frac{Y}{\sqrt{K}} u^2 \right)
\ee
where $\delta$ is the thickness of the foam block in the flow direction, $\mu$ is the viscosity of the gas, $u$ is the velocity component in the flow direction, $\rho$ is the density of the gas, $K$ is the {\ct PERMEABILITY} in units of m$^2$, and $Y$ is a dimensionless inertial term that you specify using the parameter {\ct DRAG\_COEFFICIENT}.  When using the porous media model the {\ct PERMEABILITY} and {\ct DRAG\_COEFFICIENT} must be specified for all three directions.

The {\ct INIT} line designates the volume occupied by the porous media using the sextuplet {\ct XB}. A single particle is inserted into the center of each cell occupied by the foam by specifying the parameters {\ct N\_PARTICLES\_PER\_CELL=1} and {\ct CELL\_CENTERED=.TRUE.}.

A sample calculation involving porous media is contained in the folder {\ct Sprinklers\_and\_Sprays}. The input file is called {\ct porous\_media.fds}.

\subsection{Screens}
\label{info:particle_screen}

A 2-D array of particles can be used to represent the drag exerted by a window screen, as in the following example:
\begin{lstlisting}
&INIT N_PARTICLES_PER_CELL=1, CELL_CENTERED=.TRUE., PART_ID='SCREEN',
      XB=1.01,1.02,0.0,1.0,0.0,1.0/
&PART ID='SCREEN', DRAG_LAW='SCREEN', FREE_AREA_FRACTION=0.4, STATIC=.TRUE.,
      SURF_ID='SCREEN', ORIENTATION(1:3,1)=1,0,0 /
&SURF ID='SCREEN', THICKNESS=0.00015, GEOMETRY='CYLINDRICAL',
      MATL_ID='ALUMINUM' /
&MATL ID='ALUMINUM', DENSITY=2700., CONDUCTIVITY=200., SPECIFIC_HEAT=0.9 /
\end{lstlisting}
The {\ct INIT} line designates the plane of the screen using the sextuplet {\ct XB}. A single particle is inserted into each cell by specifying the parameter {\ct N\_PARTICLES\_PER\_CELL=1}.  The particles are be defined with a {\ct SURF\_ID} containing the material properties of the screen.  A special drag law for screens is specified via the {\ct DRAG\_LAW}.  {\ct ORIENTATION} is the direction normal to the screen, and {\ct FREE\_AREA\_FRACTION} is the fraction of the screen's surface area that is open. In the example, an aluminum screen with a 40~\% free area and an 0.0003~m wire diameter is placed normal to the $x$-axis.  Note that the {\ct LENGTH} parameter on the {\ct SURF} line will be computed automatically so the fraction of the grid cell flow area occupied by the screen is equal to 1 - {\ct FREE\_AREA\_FRACTION}. The pressure drop across the screen is given by
\be
   \label{eqn_screen}
   \Delta p =  l \; \left(\frac{\mu}{K} u + \rho \frac{Y}{\sqrt{K}} u^2 \right)
\ee
where $l$ is the screen thickness (equal to the wire diameter), $\mu$ is the viscosity of the gas, $u$ is the velocity normal to the screen, $\rho$ is the density of the gas, and $Y$ and $K$ are empirical constants given by
\begin{eqnarray}
   K &=& 3.44 \times 10^{-9} \; \hbox{\ct FREE\_AREA\_FRACTION}^{1.6} \; \; \hbox{m}^2 \\
   Y &=& 0.043 \; \hbox{\ct FREE\_AREA\_FRACTION}^{2.13}
\end{eqnarray}

The {\ct MISC} input parameter {\ct PARTICLE\_CFL\_MAX} controls the time step on the pressure drop across a screen (or other porous media). If a screen or other porous media introduces numerical instabilities, reducing the value of {\ct PARTICLE\_CFL\_MAX} below 1 may resolve them.

\subsection{Electrical Cables}
\label{info:THIEF}

Petra Andersson and Patrick Van Hees of the Swedish National Testing and Research Institute (SP) have proposed that the thermally-induced electrical failure (THIEF) of a cable can be predicted via a simple one-dimensional heat transfer calculation, under the assumption that the cable can be treated as a homogeneous cylinder~\cite{Andersson:2005}. Their results for PVC cables were encouraging and suggested that the simplification of the analysis is reasonable and that it should extend to other types of cables. The assumptions underlying the THIEF model are as follows:
\begin{enumerate}
\item The heat penetration into a cable of circular cross section is largely in the radial direction. This greatly simplifies the analysis, and it is also conservative because it is assumed that the cable is completely surrounded by the heat source.
\item The cable is homogeneous in composition. In reality, a cable is constructed of several different types of polymeric materials, cellulosic fillers, and a conducting metal, most often copper.
\item The thermal properties -- conductivity, specific heat, and density -- of the assumed homogeneous cable are independent of temperature. In reality, both the thermal conductivity and specific heat of polymers are temperature-dependent, but this information is very difficult to obtain from manufacturers.
\item It is assumed that no decomposition reactions occur within the cable during its heating, and ignition and burning are not considered in the model. In fact, thermoplastic cables melt, thermosets form a char layer, and both off-gas volatiles up to and beyond the point of electrical failure.
\item Electrical failure occurs when the temperature just inside the cable jacket reaches an experimentally determined value.
\end{enumerate}
Obviously, there are considerable assumptions inherent in the Andersson and Van Hees THIEF model, but their results for various polyvinyl chloride (PVC) cables suggested that it may be sufficient for engineering analyses of a wider variety of cables. The U.S. Nuclear Regulatory Commission sponsored a study of cable failure known as CAROLFIRE~\cite{CAROLFIRE}. The primary project objective of CAROLFIRE was to characterize the various modes of electrical failure (e.g., hot shorts, shorts to ground) within bundles of power, control and instrument cables. A secondary objective of the project was to develop a simple model to predict thermally-induced electrical failure when a given interior region of the cable reaches an empirically determined threshold temperature. The measurements used for these purposes are described in Volume II of the CAROLFIRE test report. Volume III describes the modeling.

The THIEF model can only predict the temperature profile within the cable as a function of time, given a time-dependent exposing temperature or heat flux. The model does not predict at what temperature the cable fails electrically. This information is gathered from experiment. The CAROLFIRE experimental program included bench-scale, single cable experiments in which temperature measurements were made on the surface of, and at various points within, cables subjected to a uniform heat flux. These experiments provided the link between internal cable temperature and electrical failure. The model can only predict the interior temperature and infer electrical failure when a given temperature is reached. It is presumed that the temperature of the centermost point in the cable is not necessarily the indicator of electrical failure. This analysis method uses the temperature just inside the cable jacket rather than the centermost temperature, as that is where electrical shorts in a multi-conductor cable are most likely to occur first.

To use the THIEF model in FDS, add lines similar to the following to the input file:
\begin{lstlisting}
&MATL ID='plastic', DENSITY=2535., CONDUCTIVITY=0.2, SPECIFIC_HEAT=1.5 /
&SURF ID='cylinder', THICKNESS=0.00815, LENGTH=0.1, MATL_ID='plastic',
      GEOMETRY='CYLINDRICAL' /
&PART ID='Cable Segment', SURF_ID='cylinder', ORIENTATION(1:3,1)=0.,0.,1.,
      STATIC=.TRUE. /
&INIT ID='Cable', XB=0.01,0.01,0.,0.,0.,0., N_PARTICLES=1, PART_ID='Cable Segment' /
&DEVC ID='Cable Temp', INIT_ID='Cable',
      QUANTITY='INSIDE WALL TEMPERATURE', DEPTH=0.0015 /
\end{lstlisting}
The THIEF model assumes that the cable plastic material has a thermal conductivity of 0.2~\si{W/(m.K)} and a specific heat of 1.5~\si{kJ/(kg.K)}. If you change these values, you are no longer using the THIEF model. The density is the mass per unit length of the cable divided by its cross sectional area. The {\ct THICKNESS} is the radius of the cylindrical cable in units of m. The {\ct LENGTH}, in m, is needed by FDS because it assumes that the cable is a cylindrical segment of a certain length. It has no impact on the simulation, and its value it typically the size of a grid cell. The {\ct ORIENTATION} tells FDS the direction of the prevailing radiative source. The second argument indicates that there can be more than one {\ct ORIENTATION}. {\ct STATIC=.TRUE.} prevents the cable from moving. The {\ct INIT} line is used to position the cable within the computational domain. The {\ct DEVC} line records the cables inner temperature, in this case 1.5~mm below the surface. This is typically the jacket thickness.


\clearpage

\section{Particle Insertion}
\label{info:controlling_droplets}

There are three ways of introducing droplets or particles into a simulation. The first way is to define a sprinkler or nozzle using a {\ct PROP} line that includes a {\ct PART\_ID} that specifies the particle or droplet parameters. The second way is to add a {\ct PART\_ID} to a {\ct SURF} line, in which case particles or droplets will be ejected from that surface. Note that this only works if the surface has a normal velocity pointing into the flow domain. The third way to introduce particles or droplets is via an {\ct INIT} line that defines a volume within the computational domain in which the particles/droplets are to be introduced initially and/or periodically in time.

It is not unusual to include hundreds of thousands of particles in a simulation. Visualizing all of the particles in Smokeview can sometimes be impractical due to memory limitations. To limit the amount of particles, you can make use of the following parameters on the {\ct PART} line:
\begin{description}
\item[{\ct SAMPLING\_FACTOR}] Sampling factor for the output file {\ct CHID.prt5}. This parameter can be used to reduce the size of the particle output file used to animate the simulation. The default value is 1 for {\ct MASSLESS} particles, meaning that every particle or droplet will be shown in Smokeview. The default is 10 for all other types of particles. {\ct MASSLESS} particles are discussed in Section~\ref{info:MASSLESS}.
\item[{\ct AGE}]  Number of seconds the particle or droplet exists, after which time it is removed from the calculation. This is a useful parameter to use when trying to reduce the number of droplets or particles in a simulation.
\end{description}



\subsection{Particles Introduced at a Solid Surface}
\label{info:particle_flux}
\label{particle_flux}

There are two ways of introducing particles at a solid surface. You can specify a particle mass flux and inject particles regularly in time, or you can specify a particle surface density and introduce the particles at the start of the simulation.

\subsubsection{Particles specified using a mass flux}

If the particles have mass and are introduced from a solid surface, specify {\ct PARTICLE\_MASS\_FLUX} on the {\ct SURF} line. The number of particles inserted at each solid cell every {\ct DT\_INSERT} seconds is specified by {\ct NPPC} (Number of Particles Per Cell) on the {\ct SURF} line defining the solid surface. The default value of {\ct DT\_INSERT} is 0.01~s and {\ct NPPC} is 1. As an example, the following set of input lines:
\begin{lstlisting}
&PART ID='particles', ... /
&SURF ID='SLOT', PART_ID='particles', VEL=-5., PARTICLE_MASS_FLUX=0.1 /
&OBST XB=-0.2,0.2,-0.2,0.2,4.0,4.4, SURF_IDS='INERT','SLOT','INERT' /
\end{lstlisting}
creates an obstruction that ejects particles out of its sides at a rate of 0.1~\si{kg/(m$^2$.s)} and a velocity of 5~m/s (the minus sign indicates the particles are ejected from the surface). FDS will adjust the mass flux if the obstruction or vent dimensions are changed to conform to the numerical grid. The {\ct ID}s have no meaning other than as identifiers. The surface on which particles are specified must have a non-zero normal velocity directed into the computational domain. This happens automatically if the surface is burning, but must be specified if it is not. There is a simple input file called {\ct particle\_flux.fds} that demonstrates how the above input lines can produce a stream of particles from a block. The total mass flux from the block is the product of the {\ct PARTICLE\_MASS\_FLUX} times the total area of the sides of the block, 0.4~m $\times$ 0.4~m $\times$ 4. The expected accumulated mass of particles on the ground after 10~s is expected to be 0.64~kg, as shown in Fig.~\ref{particle_flux_fig}.

\begin{figure}[ht]
\begin{center}
\includegraphics[height=2.2in]{SCRIPT_FIGURES/particle_flux}
\end{center}
\caption[Results of the {\ct particle\_flux} test case]{Simple test case to demonstrate mass conservation of particles ejected from an obstruction.}
\label{particle_flux_fig}
\end{figure}

Note also that you can independently control particles that emanate from a solid surface. For example, a device might control the activation of a fan, but you can over-ride the device and control the particles separately. To do this, specify either a device or controller via a {\ct DEVC\_ID} or {\ct CTRL\_ID} on the {\ct PART} line that defines the particles. For more information on devices and controls, see Sections~\ref{info:basic_control}~and~\ref{info:CTRL}.

\subsubsection{Particles specified using a surface density}

Instead of a mass flux, you can specify the {\ct PARTICLE\_SURFACE\_DENSITY} (kg/m$^2$) for particles introduced at the start of a simulation. You can introduce {\ct NPPC} particles per cell, although 1 is sufficient to represent the specified surface density. This feature is useful for creating subgrid-scale dry vegetative fuels.


\subsection{Particles or Droplets Introduced at a Sprinkler or Nozzle}
\label{info:sprinkler_droplets}

A sprinkler or nozzle is added to the simulation using a {\ct PROP} line to describe the features of the device and a {\ct DEVC} line to position and orient the device within the computational domain. {\ct PARTICLES\_PER\_SECOND} is the  number of droplets inserted every second per active sprinkler or nozzle (Default 5000). It is listed on the {\ct PROP} line that includes other properties of the sprinkler or nozzle. Note that this parameter only affects sprinklers and nozzles. Changing this parameter does {\em not} change the flow rate, but rather the number of droplets used to represent the flow.

Note that {\ct PARTICLES\_PER\_SECOND} can be a very important parameter. In some simulations, it is a good idea to increase this number so that the liquid mass is distributed more uniformly over the droplets. If this parameter is too small, it can lead to a non-physical evaporation pattern, sometimes even to the point of causing a numerical instability. If you encounter a numerical instability shortly after the activation of a sprinkler or nozzle, consider increasing {\ct PARTICLES\_PER\_SECOND} to produce a smoother evaporation pattern that is more realistic. Keep in mind that for a real sprinkler or nozzle, there are many more droplets created per second than the number that can be simulated.

Note that by default the parameter {\ct PARTICLE\_CFL} is set to {\ct .FALSE.} (see Section \ref{info:PART_Stability}).  Thus, particles inserted with a velocity faster than the local fluid entrainment velocity may traverse more than one cell.  If the particles represent a fuel spray or sprinkler droplets that are to be collected in a pan, it may be necessary to set {\ct PARTICLE\_CFL=.TRUE.} on {\ct MISC} to precisely account for particle mass.  For example, the particles may represent liquid fuel being sprayed into a pan burner made from a zero thickness obstruction.  In this case, if the particle position overshoots the cell face representing the boundary of the pan then either spurious burning of the particle will occur underneath the pan or, if the particle does not burn, the heat release rate will be diminished.


\subsection{Particles or Droplets Introduced within a Volume}
\label{info:initial_droplets}

Sometimes it is convenient to introduce Lagrangian particles within a particular region of the domain. To do this, use an {\ct INIT} line which contains the {\ct PART\_ID} for the type of particle to be inserted. Particles specified via an {\ct INIT} line can represent a number of different kinds of subgrid-scale objects. The particles can be massless tracers or they can be solid or liquid particles with mass. If not massless, specify {\ct MASS\_PER\_VOLUME} in units of kg/m$^3$. Do not confuse this parameter with {\ct DENSITY}, explained in the next section. For example, water has a {\ct DENSITY} of 1000~kg/m$^3$, whereas a liter of water broken up into droplets and spread over a cubic meter has a {\ct MASS\_PER\_VOLUME} of 1~kg/m$^3$. The number of Lagrangian particles inserted is controlled by the parameter {\ct N\_PARTICLES}.

\subsubsection{Randomly Distributed Particles within a Specified Volume}

The parameter {\ct N\_PARTICLES} on the {\ct INIT} line indicates the number of particles to insert within a specified region of the domain. This region can take on a number of shapes, depending on the parameter {\ct SHAPE = (['BLOCK']\footnote{There is no need to specify {\ct SHAPE='BLOCK'}, just omit {\ct SHAPE} in this case.},'CONE','LINE','RING')}. For {\ct 'BLOCK'}, {\ct 'CONE'}, and {\ct 'RING'} the particle positions are randomly distributed by default.  For {\ct 'RING'} you can position the particles uniformly by setting {\ct UNIFORM=.TRUE.} on the {\ct INIT} line.  By default, the region is a rectangular {\ct 'BLOCK'} designated with the real sextuplet {\ct XB}. The format for {\ct XB} is the same as that used on the {\ct OBST} line.
\begin{lstlisting}
&INIT PART_ID='my particles', XB=..., N_PARTICLES=..., MASS_PER_VOLUME=... /
\end{lstlisting}
Note that the volume of the specified region is calculated according to the {\ct SHAPE} dimensions, regardless of whether there are solid obstructions within this region. Note also that in most applications, the number of particles, {\ct N\_PARTICLES}, is somewhat arbitrary but should be chosen to provide at least a few particles per grid cell. FDS will then automatically assign a weighting factor to each particle to ensure that the {\ct MASS\_PER\_VOLUME} is achieved. In some applications, on the other hand, it may be important to specify the number of particles. For example, if using particles to model the burning of electrical cables, you may want to specify how many cables are actually burning.

If the volume specified by the sextuplet {\ct XB} crosses mesh boundaries, be aware that {\ct N\_PARTICLES} refers to the entire volume, not just the volume within a particular mesh. FDS will automatically compute the necessary number of particles to assign to each mesh.

Alternatively, you can specify {\ct SHAPE='CONE'}, in which case the particles will be randomly distributed within a vertical cone. This is primarily used for representing trees. The dimensions of the cone are specified via the parameters {\ct RADIUS}, {\ct HEIGHT}, and base position {\ct XYZ}. The latter is a triplet of real numbers designating the point at the center of the base of the cone. Here is an example of how one might make a tree:
\begin{lstlisting}
&PART ID='tree crown foliage',
      DRAG_LAW='CYLINDER',
      SURF_ID='needles',
      QUANTITIES='PARTICLE TEMPERATURE','PARTICLE MASS','PARTICLE DIAMETER',
      STATIC=.TRUE.,
      COLOR='FOREST GREEN' /
&INIT PART_ID='tree crown foliage',
      XYZ=0.0,0.0,0.0,
      RADIUS=1,
      HEIGHT=2,
      SHAPE='CONE',
      N_PARTICLES_PER_CELL=1,
      CELL_CENTERED=.TRUE.,
      MASS_PER_VOLUME=2.0  /
\end{lstlisting}
Note that in this example, exactly one particle is specified per grid cell, positioned exactly in the center of the cell. The number of actual pine needles this single particle represents depends on the specified {\ct MASS\_PER\_VOLUME} and the mass of an individual cylindrical particle. That information would be provided by the {\ct SURF} line {\ct 'needles'}.

\subsubsection{Specifying a Fixed Number of Particles per Grid Cell}

There are special applications where you might want to specify {\ct N\_PARTICLES\_PER\_CELL} to indicate the number of particles within each grid cell of a specified region. When using {\ct N\_PARTICLES\_PER\_CELL}, the particles will be randomly placed within each cell.  If you set {\ct CELL\_CENTERED=.TRUE.}, the particles will be placed at the center of each cell.

\subsubsection{Specifying a Weight Factor for Particles}

Use {\ct PARTICLE\_WEIGHT\_FACTOR} to specify how many actual particles each of the computational particles represent. This can be used in conjunction with {\ct N\_PARTICLES\_PER\_CELL} to reduce the computational cost when a large number of identical particles would be placed in the same grid cell.


\subsubsection{Single Particle Insertion}
\label{bucket_test_3}

If you introduce only a single particle, which is often a handy way of creating a target, you may use the real triplet {\ct XYZ} rather than {\ct XB} to designate the particle's position.  You can give this single particle an initial velocity using the real triplet {\ct UVW}. You can also add {\ct DX}, {\ct DY}, and/or {\ct DZ} to create a line of particles that are offset from {\ct XYZ} by these increments in units of meters. For example,
\begin{lstlisting}
&INIT PART_ID='target', XYZ=1.2,3.4,5.6, N_PARTICLES=10, DX=0.1 /
\end{lstlisting}
creates a line of 10 particles starting at the point (1.2,3.4,5.6) separated by 0.1~m. This is handy for creating arrays of devices, like heat flux gauges. See Section~\ref{info:heat_flux} for more details.

In special cases, you might want a single liquid droplet to be inserted at a particular point with a particular velocity every {\ct DT\_INSERT}~s following the activation of a particular device, as follows:
\begin{lstlisting}
&INIT N_PARTICLES=1, XYZ=..., UVW=..., DIAMETER=200., DT_INSERT=0.05,
      PART_ID='drops', DEVC_ID='nozzle' /
\end{lstlisting}
Note that the {\ct DIAMETER} ($\mu$m) on the {\ct INIT} line is only valid for liquid droplets. It over-rides the {\ct DIAMETER} on the {\ct PART} line labeled {\ct 'drops'}. A simple test case that demonstrates this functionality is called {\ct bucket\_test\_3}, in which water droplets are launched in different directions from a common point. Their size, velocity, insertion frequency, and mass flux are varied, and a check is made that water mass is conserved (see Fig.~\ref{bucket_test_3_fig}).

\begin{figure}[ht]
\centering
\includegraphics[scale=0.55]{SCRIPT_FIGURES/bucket_test_3}
\caption[Results of the {\ct bucket\_test\_3} case]{Accumulated water collected at the floor in the {\ct bucket\_test\_3} case.}
\label{bucket_test_3_fig}
\end{figure}

\subsubsection{Periodic Insertion of Particles within a Specified Volume}

If you want to introduce particles within a given region periodically in time and not just initially, set {\ct DT\_INSERT} on the {\ct INIT} line to a positive value indicating the time increment (s) for insertion. The parameter {\ct N\_PARTICLES} now indicates the number of droplets/particles inserted every {\ct DT\_INSERT} seconds. If the droplets/particles have mass, use {\ct MASS\_PER\_TIME} (kg/s) instead of {\ct MASS\_PER\_VOLUME} to indicate how much mass is to be introduced per second.

If you want to delay the insertion of droplets, you can use either a {\ct DEVC\_ID} or a {\ct CTRL\_ID} on the {\ct INIT} line to name the controlling device. See Section~\ref{info:basic_control} for more information on controlling devices.


\clearpage

\section{Special Topic: Suppression by Water}
\label{info:suppression}

Modeling fire suppression by water has three principal components: transporting the water droplets through the air, tracking the water along the solid surface, and predicting the reduction of the burning rate. This section addresses the latter two.


\subsection{Velocity on Solid Surfaces}
\label{info:surface_droplets}

When a droplet strikes a solid surface\footnote{If you do not want droplets to accumulate on solid surfaces, set {\ct ALLOW\_SURFACE\_PARTICLES=.FALSE.} on the {\ct MISC} line. It is normally {\ct .TRUE.}}, it sticks and is reassigned a new speed and direction. If the surface is horizontal, the direction is randomly chosen. If vertical, the direction is downwards. The rate at which the droplets move over the horizontal and vertical surfaces is difficult to quantify. The parameters {\ct HORIZONTAL\_VELOCITY} and {\ct VERTICAL\_VELOCITY} on the {\ct PART} line allow you to control the rate at which droplets move horizontally or vertically (downward). The defaults are 0.2~m/s and 0.5~m/s, respectively.

There are some applications, like the suppression of racked storage commodities, where it is useful to allow water droplets to move horizontally along the underside of a solid object. It is difficult to model this phenomenon precisely because it involves surface tension, surface porosity and absorption, and complicated geometry. However, a way to capture some of the effect is to set {\ct ALLOW\_UNDERSIDE\_PARTICLES=.TRUE.} on the {\ct MISC} line. It is normally false. Also, note that when droplets hit obstructions, the vertical direction is assumed to coincide with the $z$ axis, regardless of any change to the gravity vector, {\ct GVEC}.

A useful sample case to demonstrate various features of droplet motion on solid obstructions is the test case called {\ct cascade.fds}. Figure~\ref{cascade} shows a stream of water droplets impinging on the top of a box followed by the cascading of water droplets over the top edge.

\begin{figure}[ht]
\begin{center}
\begin{tabular}{lcr}
\includegraphics[height=3in]{SCRIPT_FIGURES/cascade_1} &
\includegraphics[height=3in]{SCRIPT_FIGURES/cascade_2} &
\includegraphics[height=3in]{SCRIPT_FIGURES/cascade_3}
\end{tabular}
\end{center}
\caption[Example of water cascading over solid obstructions]{Smokeview rendering of the {\ct cascade} test case.}
\label{cascade}
\end{figure}


\subsection{Reduction of the Burning Rate}
\label{e_coefficient}

Water reduces the fuel pyrolysis rate by cooling the fuel surface and also changing the chemical reactions that liberate fuel gases from the solid. If the solid or liquid fuel has been given reaction parameters via the {\ct MATL} line, there is no need to set any additional suppression parameters. It is assumed that water impinging on the fuel surface takes energy away from the pyrolysis process and thereby reduces the burning rate of the fuel. If the surface has been assigned a {\ct HRRPUA} (Heat Release Rate Per Unit Area), a parameter needs to be specified that governs the suppression of the fire by water because this type of simulated fire essentially acts like a gas burner whose flow rate is explicitly specified. An empirical way to account for fire suppression by water is to characterize the reduction of the pyrolysis rate in terms of an exponential function. The local mass loss rate of the fuel is expressed in the form
\be
   \dm_{\rm f}''(t) = \dm_{\rm f,0}''(t) \; {\rm e}^{-\int k(t) \; dt} \label{nistexting}
\ee
Here $\dm_{\rm f,0}''(t)$ is the user-specified burning rate per unit area when no water is applied and $k$ is a function of the local water mass per unit area, $m_{\rm w}''$, expressed in units of kg/m$^2$.
\be
k(t) = \hbox{\ct E\_COEFFICIENT} \; m_{\rm w}''(t) \quad          \si{1/s}
\ee
The parameter {\ct E\_COEFFICIENT} must be obtained experimentally, and it is expressed in units of \si{m$^2$/(kg.s)}. Usually, this type of suppression algorithm is invoked when the fuel is complicated, like a cartoned commodity.  The example case {\ct e\_coefficient} demonstrates the use of this parameter.  A sprinkler is placed over a burner defined with an {\ct E\_COEFFICIENT} as shown below.  The sprinkler is set to operate at 5~s.  Figure~\ref{e_coef_fig} shows the heat release rate and burning rate. Note that expected value is computed using the sprinkler flow rate and the FDS results are delayed slightly by the time it takes for droplets to reach and accumulate on the burning surface.
\begin{lstlisting}
&SURF ID='FUEL', HRRPUA=100., E_COEFFICIENT=4. /
\end{lstlisting}

\begin{figure}[ht]
\begin{tabular*}{\textwidth}{lr}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/e_coefficient_q} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/e_coefficient_br}
\end{tabular*}
\caption[Results of the {\ct e\_coefficient} test case]{Output of the  {\ct e\_coefficient} test case.}
\label{e_coef_fig}
\end{figure}



\chapter{Devices and Control Logic}

Sprinklers, smoke detectors, heat flux gauges, and thermocouples may seem to be completely unrelated, but from the point of view of FDS, they are simply devices that operate in specific ways depending on the properties assigned to them. They can be used to record some quantity of the simulated environment, like a thermocouple, or they can represent a mathematical model of a complex sensor, like a smoke detector, and in some cases they can trigger events to happen, like a timer.

All devices, in the broadest sense of the word, are designated via the namelist group {\ct DEVC}. In addition, advanced functionality and properties are accommodated via additional namelist groups called {\ct CTRL} (Control) and {\ct PROP} (Properties).


\section{Device Location and Orientation: The \texorpdfstring{{\tt DEVC}}{DEVC} Namelist Group (Table \ref{tbl:DEVC})}
\label{info:DEVC}

Regardless of the specific properties, each device needs to be sited either at a point within the computational domain, or
over a span of the domain, like a beam smoke detector. For example, a sprinkler is sited within the domain with a line like:
\begin{lstlisting}
&DEVC XYZ=3.0,5.6,2.3, PROP_ID='Acme Sprinkler 123', ID='Spk_39' /
\end{lstlisting}
The physical coordinates of the device are given by a triplet of real numbers, {\ct XYZ}.  FDS uses these coordinates to determine in which gas or wall cell the device is located. Devices are evaluated using cell centered or face centered values of the cell the device is located in; no interpolation is done. The properties of the device are contained on the {\ct PROP} line designated by {\ct PROP\_ID}, which will be explained below for each of the special devices included in FDS. The character string {\ct ID} is merely a descriptor to identify the device in the output files, and if any action is tied to its activation.

Not all devices need to be associated with a particular set of properties via the {\ct PROP\_ID}. For example, pointwise output quantities are specified with a single {\ct DEVC} line, like
\begin{lstlisting}
&DEVC ID='TC-23', XYZ=3.0,5.6,2.3, QUANTITY='TEMPERATURE'  /
\end{lstlisting}
which tells FDS to record the temperature at the given point as a function of time. The {\ct ID} is a label in the output file whose name is {\ct CHID\_devc.csv}. Note that FDS outputs the data stored for that cell without performing any interpolation with surrounding cells.

Some devices have a particular orientation. The parameter {\ct IOR} (Index of Orientation) is required for any device that is placed on the surface of a solid. The values $\pm$1 or $\pm$2 or $\pm$3 indicate the direction that the device ``points.'' For example, {\ct IOR=-1} means that the device is mounted on a wall that faces in the negative $x$ direction. {\ct ORIENTATION} is used for devices that are not on a surface and require a directional specification, like a sprinkler. {\ct ORIENTATION} is specified with a triplet of real number values that indicate the components of the direction vector. The default value of {\ct ORIENTATION} is (0,0,-1). For example, a default downward-directed sprinkler spray can be redirected in other direction.
If you were to specify
\begin{lstlisting}
&DEVC XYZ=3.0,5.6,2.3, PROP_ID='...', ID='...', ORIENTATION=0.707,0.707,0.0 /
\end{lstlisting}
the sprinkler would point in the direction halfway between the positive $x$ and $y$ directions. For other devices, the {\ct ORIENTATION} would only change the way the device is drawn by Smokeview.

The delivered density to the floor from a sprinkler depends upon where the sprinkler arms are located.  Rather than redefining the spray pattern for every possible direction that the sprinkler can be attached to the pipe, the {\ct DEVC} can be given the parameter {\ct ROTATION}.  The default {\ct ROTATION} is 0 degrees, which for a downwards pointing sprinkler is the positive x-axis.  Positive {\ct ROTATION} will rotate the 0 degree point towards the positive y-axis.

\section{Device Output}
\label{info:out:DEVC}

Each device has a {\ct QUANTITY} associated with it. The time history of each {\ct DEVC} quantity is output to a comma-delimited ASCII file called {\ct CHID\_devc.csv} (see Section~\ref{out:DEVC} for output file format). This file can be imported into most spreadsheet software packages.  Most spreadsheet programs limit the number of columns to some number (for example the 2003 version Microsoft Excel had a 256 column limit).  As a default, FDS places no limit on the amount of columns in a comma-separated value (.csv) file.  If your spreadsheet application allows fewer columns than the number of {\ct DEVC} or {\ct CTRL} in your input file then set {\ct COLUMN\_DUMP\_LIMIT} equal to {\ct .TRUE.} on the {\ct DUMP} line. Use {\ct DEVC\_COLUMN\_LIMIT} and {\ct CTRL\_COLUMN\_LIMIT} to indicate the limit of columns in the device and control output files. Their default values are 254. If more devices or controls are present than the limit, then multiple output files will be written. The file name will have a number appended to it. For example, if two device file are required, they will be named {\ct CHID\_1\_devc.csv} and {\ct CHID\_2\_devc.csv}.

By default, the {\ct DEVC} output is written to a file every {\ct DT\_DEVC} seconds. This time increment is specified on the {\ct DUMP} line. Also, by default, a time-averaged value over the interval {\ct DT\_DEVC} is written out for each quantity of interest. To prevent FDS from time-averaging the {\ct DEVC} output, add {\ct TIME\_AVERAGED=.FALSE.} to the {\ct DEVC} line.

A useful option for the {\ct DEVC} line is to add {\ct RELATIVE=.TRUE.}, which will indicate that only the change in the initial value of the {\ct QUANTITY} is to be output. This can be useful for verification and validation studies. You can also output the absolute value of the device quantity by setting {\ct ABSOLUTE\_VALUE} to {\ct .TRUE.} on the {\ct DEVC} line.

You can change the values of the output {\ct QUANTITY} by multiplying by {\ct CONVERSION\_FACTOR} and/or adding {\ct CONVERSION\_ADDEND}. For example, to change temperature output from the default $^\circ$C to $^\circ$F, the {\ct CONVERSION\_FACTOR} should be set to 1.8 and the {\ct CONVERSION\_ADDEND} to 32. You can then change the units that appear in the output files by setting {\ct UNITS='F'} or whatever the case may be. If you do not convert the output {\ct QUANTITY} from its default value, you need not set the {\ct UNITS}.

If you do not want the {\ct DEVC} {\ct QUANTITY} to be included in the output file, set {\ct OUTPUT=.FALSE.} on the {\ct DEVC} line. Sometimes, devices are just used as clocks or control devices. In these cases, you might want to prevent its output from cluttering the output file. If the {\ct DEVC} {\ct QUANTITY='TIME'}, then {\ct OUTPUT} is set to {\ct .FALSE.} automatically.

All devices must have a specified {\ct QUANTITY}.  Some special devices (Section~\ref{info:PROP}) have their {\ct QUANTITY} specified on a {\ct PROP} line. A {\ct QUANTITY} specified on a {\ct PROP} line associated with a {\ct DEVC} line will override a {\ct QUANTITY} specified on the {\ct DEVC} line.



\newpage

\section{Special Device Properties: The \texorpdfstring{{\tt PROP}}{PROP} Namelist Group (Table \ref{tbl:PROP})}
\label{info:PROP}

Many devices are fairly easy to describe, like a point measurement, with only a few parameters which can be included on the {\ct DEVC} line. However, for more complicated devices, it is inconvenient to list all of the properties on each and every {\ct DEVC} line. For example, a simulation might include hundreds of sprinklers, but it is tedious to list the properties of the sprinkler each time the sprinkler is sited. For these devices, use a separate namelist group called {\ct PROP} to store the relevant parameters. Each {\ct PROP} line is identified by a unique {\ct ID}, and invoked by a {\ct DEVC} line by the string {\ct PROP\_ID}. The best way to describe the {\ct PROP} group is to list the various special devices and their properties.


\subsection{Sprinklers}
\label{info:sprinklers}

To specify one or more sprinklers, you need to specify several different groups of parameters that fall into a variety of namelist groups. For example, here is a basic sprinkler description:
\begin{lstlisting}
&SPEC ID='WATER VAPOR' /
&PART ID='my droplets', DIAMETER=1000., SPEC_ID='WATER VAPOR' /
&PROP ID='K-11', QUANTITY='SPRINKLER LINK TEMPERATURE', RTI=148., C_FACTOR=0.7,
      ACTIVATION_TEMPERATURE=74., OFFSET=0.10, PART_ID='my droplets', FLOW_RATE=189.3,
      PARTICLE_VELOCITY=10., SPRAY_ANGLE=30.,80., SMOKEVIEW_ID='sprinkler_upright'   /
&DEVC ID='Spr-1', XYZ=22.8,19.7,7.4, PROP_ID='K-11' /
&DEVC ID='Spr-2', XYZ=22.8,22.7,7.4, PROP_ID='K-11' /
\end{lstlisting}
A sprinkler, known as {\ct 'Spr-1'}, is located at a point in space given by {\ct XYZ}. It is a {\ct 'K-11'} type sprinkler, whose properties are given on the {\ct PROP} line. Note that the various names ({\ct ID}s) mean nothing to FDS, except as a means of associating one thing with another, so try to use {\ct ID}s that are meaningful.  The parameter {\ct QUANTITY='SPRINKLER LINK TEMPERATURE'} {\em does} have a specific meaning to FDS, directing it to compute the activation of the device using the standard RTI (Response Time Index~\cite{Heskestad:3}) algorithm. Properties associated with sprinklers included in the {\ct PROP} group are:
\begin{description}
\item[{\ct RTI}] Response Time Index in units of (m$\cdot$s)$^{1/2}$. (Default 100.)
\item[{\ct C\_FACTOR}] Conduction Factor in units of (m/s)$^{1/2}$. (Default 0.)
\item[{\ct ACTIVATION\_TEMPERATURE}] in units of $^\circ$C. (Default 74~$^\circ$C)
\item[{\ct INITIAL\_TEMPERATURE}] of the link in units of $^\circ$C. (Default {\ct TMPA})
\item[{\ct FLOW\_RATE} or {\ct MASS\_FLOW\_RATE}] in units of L/min or kg/s. An alternative is to provide the {\ct K\_FACTOR} in units of $\si{L/(min.bar^{\ha})}$ and the {\ct OPERATING\_PRESSURE}, the gauge pressure at the sprinkler, in units of bar. The flow rate is then given by $K \sqrt{p}$. Note that 1 bar is equivalent to 14.5~psi, 1 gpm is equivalent to 3.785~L/min, 1~gpm/psi$^\ha$ is equivalent to 14.41~L/min/bar$^\ha$.  If {\ct MASS\_FLOW\_RATE} is given then {\ct PARTICLE\_VELOCITY} must also be defined. Note that {\ct FLOW\_RATE} is only appropriate for liquid droplets; solid particles should use {\ct MASS\_FLOW\_RATE}
\item[{\ct OFFSET}] Radius (m) of a sphere surrounding the sprinkler where the water droplets are initially placed in the simulation. It is assumed that beyond the {\ct OFFSET} the droplets have completely broken up and are transported independently of each other. (Default 0.05~m)
\item[{\ct PARTICLE\_VELOCITY}]  Initial droplet velocity. (Default 0~m/s)
\item[{\ct ORIFICE\_DIAMETER}] Diameter of the nozzle orifice in m (default 0~m). This input provides an alternative way to set droplet velocity by giving values for {\ct FLOW\_RATE} and {\ct ORIFICE\_DIAMETER}, in which case the droplet velocity is computed by dividing the flow rate by the orifice area. Use this method if you do not have any information about droplet velocity. However, quite often you must fine-tune the {\ct PARTICLE\_VELOCITY} in order to reproduce a particular spray profile. The {\ct ORIFICE\_DIAMETER} is not used if either {\ct PARTICLE\_VELOCITY} or {\ct SPRAY\_PATTERN\_TABLE} is specified.
\item[{\ct SPRAY\_ANGLE}] A pair of angles (in degrees) through which the droplets are sprayed. The angles outline a conical spray pattern relative to the south pole of the sphere centered at the sprinkler with radius {\ct OFFSET}. For example, {\ct SPRAY\_ANGLE=30.,80.} directs the water spray through a band between 30$^\circ$ and 80$^\circ$ of the {\ct ORIENTATION} vector, which is (0,0,-1) by default (see Figure~\ref{Sprinkler_Sketch}). Elliptical spray patterns can be specified via a pair of spray angles. For example, {\ct SPRAY\_ANGLE(1:2,1)=0.,60.}  and {\ct SPRAY\_ANGLE(1:2,2)=0.,30.}, defines a spray pattern with 60 degree angle in the direction of the $x$ axis and a 30 degree angle in the direction of the $y$ axis. From above, the spray pattern resembles an ellipse. {\ct SPRAY\_PATTERN\_SHAPE} determines how the droplets are distributed within the specified {\ct SPRAY\_ANGLE}. Choices are {\ct 'UNIFORM'} and {\ct 'GAUSSIAN'}. The default distribution is {\ct 'GAUSSIAN'}. The parameter {\ct SPRAY\_PATTERN\_MU} controls the latitude of the maximum density of droplets for the {\ct 'GAUSSIAN'} distribution. The width of the distribution is controlled by the parameter {\ct SPRAY\_PATTERN\_BETA}.
\item[{\ct SPRAY\_PATTERN\_TABLE}] Name of a set of {\ct TABL} lines containing the description of the spray pattern.
\item[{\ct PART\_ID}] The name of the {\ct PART} line containing properties of the droplets. See Chapter~\ref{info:PART} for additional details.
\item[{\ct PRESSURE\_RAMP}] The name of the {\ct RAMP} lines specifying the dependence of pipe pressure on the number of active sprinklers and nozzles.
\item[{\ct SMOKEVIEW\_ID}] The name of a drawing of a sprinkler to include in the Smokeview animation.
\end{description}
Be aware that sprinklers can produce many droplets. To limit the computational cost, liquid droplets disappear when they hit the ``floor'' of the computational domain, regardless of whether it is solid or not. This feature mimics the presence of floor drains. To stop FDS from removing liquid droplets from the floor of the domain, add the phrase {\ct POROUS\_FLOOR=.FALSE.} to the {\ct MISC} line. Be aware, however, that droplets that land on the floor continue to move horizontally in randomly selected directions; bouncing off obstructions, and consuming CPU time. Note also that solid particles do not disappear from the floor of the domain like liquid droplets.

Do not locate a sprinkler or nozzle within {\ct OFFSET} meters of a mesh boundary. If you do, the droplets introduced into the adjacent mesh will be rejected. The entire spray pattern of the sprinkler need not lie within one mesh, but the volume immediately surrounding the sprinkler itself must lie in one mesh.

\begin{figure}[ht]
\includegraphics[width=6.5in]{FIGURES/Sprinkler_Sketch}
\caption[Sketch of sprinkler spray]{Sketch showing the role of {\ct OFFSET} and {\ct SPRAY\_ANGLE}.}
\label{Sprinkler_Sketch}
\end{figure}


\subsubsection{Special Topic: Specifying Complex Spray Patterns}
\label{info:spraypattern}
\label{info:TABL}
\label{bucket_test_2}

As an example of the more advanced sprinkler options, a sprinkler with an elliptical spray pattern and uniform mass flux distribution within the spray angle is given by:
\begin{lstlisting}
&PROP ... SPRAY_ANGLE(1:2,1)=0.,60., SPRAY_ANGLE(1:2,2)=0.,30.,
      SPRAY_PATTERN_SHAPE='UNIFORM' /
\end{lstlisting}
For full-cone sprays, the parameter {\ct SPRAY\_PATTERN\_MU} is set to zero by default. For hollow-cone sprays it is set to the average of {\ct SPRAY\_ANGLE(1:2,1)}, the spray angle in the $x$ direction. The following example uses  {\ct SPRAY\_PATTERN\_MU} to define a spray that is somewhere between a full-cone and a hollow-cone spray:
\begin{lstlisting}
&PROP ... SPRAY_ANGLE=0.,30., SPRAY_PATTERN_MU=15. /
\end{lstlisting}
If a more complex spray pattern is desired than one characterized by a {\ct SPRAY\_ANGLE}, then a \linebreak[4]{\ct SPRAY\_PATTERN\_TABLE} can be specified using the {\ct TABL} namelist group. Specify the total flow using {\ct FLOW\_RATE} on the {\ct PROP} line, the name of the spray pattern using {\ct SPRAY\_PATTERN\_TABLE} and then one or more {\ct TABL} lines of the form:
\begin{lstlisting}
&TABL ID='table_id', TABLE_DATA=LAT1,LAT2,LON1,LON2,VELO,FRAC /
\end{lstlisting}
where each {\ct TABL} line for a given {\ct 'table\_id'} provides information about the spherical distribution of the spray pattern for a specified solid angle. {\ct LAT1} and {\ct LAT2} are the bounds of the solid angle measured in degrees from the south pole (0 is the south pole and 90 is the equator, 180 is the north pole).  Note that this is not the conventional way of specifying a latitude, but rather a convenient system based on the fact that a typical sprinkler sprays water downwards, which is why 0 degrees is assigned to the ``south pole,'' or the $-z$ direction. The parameters {\ct LON1} and {\ct LON2} are the bounds of the solid angle (also in degrees), where 0 (or 360) is aligned with the $-x$ axis and 90 is aligned with the $-y$ axis.  {\ct VELO} is the velocity (m/s) of the droplets at their point of insertion. {\ct FRAC} the fraction of the total flow rate of liquid that should emerge from that particular solid angle.

In the test case called {\ct bucket\_test\_2}, the spray consists of two jets, each with a velocity of 5~m/s and a combined flow rate of 60~L/min. The sprinkler is set to operate for only 5~s. The first jet contains 0.2 of the total flow, the second, 0.8 of the total. The jets are centered at points 60$^\circ$ below the ``equator,'' and are separated by 180$^\circ$.
\begin{lstlisting}
&PROP ... FLOW_RATE=60., SPRAY_PATTERN_TABLE='TABLE1' /
&TABL ID='TABLE1', TABLE_DATA=30,31,  0,  1,5,0.2 /
&TABL ID='TABLE1', TABLE_DATA=30,31,179,180,5,0.8 /
\end{lstlisting}
Note that each set of {\ct TABL} lines must have a unique {\ct ID}.  Also note that the {\ct TABL} lines can be specified in any order. Figure~\ref{bucket_test_2_fig} verifies that the sprinkler releases 5~kg of water (1~kg/s for 5~s).

\begin{figure}[ht]
\centering
\includegraphics[height=2.2in]{SCRIPT_FIGURES/bucket_test_2}
\caption[Results of the {\ct bucket\_test\_2} case]{Accumulated water collected at the floor in the {\ct bucket\_test\_2} case.}
\label{bucket_test_2_fig}
\end{figure}




\subsubsection{Special Topic: Varying Pipe Pressure}
\label{info:pressureramp}

In real sprinkler systems, the pipe pressure is affected by the number of actuated sprinklers. Typically, the pressure is higher than the design value when the first sprinkler activates, and decreases as more and more sprinklers are activated. The pipe pressure has an effect on flow rate, droplet velocity and droplet size distribution. In FDS, the varying pipe pressure can be specified on a {\ct PROP} line using {\ct PRESSURE\_RAMP}. On each {\ct RAMP} line, the number of open sprinklers or nozzles is associated with certain pipe pressure (bar). For example:
\begin{lstlisting}
&PROP ID='My nozzle'
      OFFSET=0.1
      PART_ID='water drops'
      FLOW_RATE=0.9
      OPERATING_PRESSURE = 10.0
      PARTICLE_VELOCITY=15.0
      SPRAY_ANGLE=0.0,80.0
      PRESSURE_RAMP = 'PR1' /

&RAMP ID = 'PR1' T = 1, F = 16. /
&RAMP ID = 'PR1' T = 2, F = 10. /
&RAMP ID = 'PR1' T = 3, F = 8. /
\end{lstlisting}
These lines would indicate that the pressure is 16~bar when the first sprinkler activates, 10~bar when two sprinklers are active, and 8~bar when three or more sprinklers are active. When counting the number of active sprinklers, FDS accounts for all active sprinklers or nozzles with a given {\ct PART\_ID}.

When pressure ramps are used, both {\ct FLOW\_RATE} and {\ct PARTICLE\_VELOCITY} are dependent on the {\ct OPERATING\_PRESSURE}. Specify either the {\ct FLOW\_RATE}, or the {\ct K\_FACTOR} and {\ct OPERATING\_PRESSURE}. In the latter case, the flow rate is given by $K \sqrt{p}$ and the droplet velocity by using the liquid density and the {\ct ORIFICE\_DIAMETER}.  If spray pattern table is used, the droplet velocity is determined separately for each line of the table by applying $K\sqrt{p}$ and the {\ct ORIFICE\_DIAMETER}. The median diameter of the particle size distribution is scaled as $d_m(p) = d_m(p_o)(p_o/p)^{1/3}$, where $p_o$ is the {\ct OPERATING\_PRESSURE} and $d_m(p_o)$ is specified by parameter {\ct DIAMETER} on the corresponding {\ct PART} line.

For some simulations there may be groups of independent sprinklers or nozzles.  For example one might have one set of nozzles for a fuel spray and a second set for water spray.  In this case the flow of water would not be impacted by how many fuel spray nozzles are open.  To have the {\ct PRESSURE\_RAMP} only count a subset of sprinklers or nozzles, the keyword {\ct PIPE\_INDEX} can be used on the {\ct DEVC} line. For example:
\begin{lstlisting}
&DEVC ID='Spr_1',  XYZ=2.00,2.00,8.00, PROP_ID='My nozzle',  PIPE_INDEX=1 /
&DEVC ID='Spr_2',  XYZ=1.00,1.00,8.00, PROP_ID='My nozzle',  PIPE_INDEX=1 /
&DEVC ID='Fuel_1', XYZ=2.00,2.00,1.00, PROP_ID='Fuel Spray', PIPE_INDEX=2 /
&DEVC ID='Fuel_2', XYZ=1.00,1.00,1.00, PROP_ID='Fuel Spray', PIPE_INDEX=2 /
\end{lstlisting}
These lines indicate that the fuel spray nozzles are a separate pipe network from the water sprinklers.  With these inputs, a {\ct PRESSURE\_RAMP} for the water sprinklers would not count any active fuel spray nozzles.  See the example case {\ct flow\_rate\_2} in the Verification Guide for further details on the use of {\ct PIPE\_INDEX}.

\subsection{Nozzles}
\label{info:nozzles}

Nozzles are very much like sprinklers, only they do not activate based on the standard RTI (Response Time Index) model. To simulate a nozzle that activates at a given time, specify a {\ct QUANTITY} and {\ct SETPOINT} directly on the {\ct DEVC} line. The following lines:
\begin{lstlisting}
&DEVC XYZ=23.91,21.28,0.50, PROP_ID='nozzle', ORIENTATION=0,0,1, QUANTITY='TIME',
      SETPOINT=0., ID='noz_1' /
&DEVC XYZ=26.91,21.28,0.50, PROP_ID='nozzle', ORIENTATION=0,0,1, QUANTITY='TIME',
      SETPOINT=5., ID='noz_2' /
&PROP ID='nozzle', PART_ID='heptane drops', FLOW_RATE=2.132,
      FLOW_TAU=-50., PARTICLE_VELOCITY=5., SPRAY_ANGLE=0.,45.    /
\end{lstlisting}
designate two nozzles of the same type, one which activates at time zero, the other at 5~s. Note that nozzles must have a designated
{\ct PROP\_ID}, and the {\ct PROP} line must have a designated {\ct PART\_ID} to describe the liquid droplets.

\subsubsection{Example Case: Setting the Flow Rate of a Nozzle}
\label{flow_rate}

This example demonstrates the use of pressure ramps and control logic for opening and closing nozzles. It also serves as a verification test for the water flow rate. There are four nozzles that open at designated times: 0 s, 15 s, 30 s and 45 s. At time 60 s, all the nozzles are closed. The number of open nozzles is measured using a device with quantity {\ct 'OPEN NOZZLES'}. A comparison of the FDS result and the exact, intended values is shown in Fig.~\ref{flow_rate_fig}.  Note that {\ct 'OPEN NOZZLES'} counts only nozzles belonging to the specified {\ct PIPE\_INDEX}. The pressure ramp has been designed to deliver a total flow rate of 10~L/min at all values of open nozzles. Mathematically this means that
\be
n K \sqrt{p} = 10 \;\hbox{L/min} \quad \Rightarrow \quad
p = \left( \frac{10 \;\hbox{L/min}}{n K}\right)^2
\ee
where $n$ is the number of open nozzles. The corresponding nozzle and pressure ramp definitions are
\begin{lstlisting}
&PROP ID='Head', OFFSET=0.10, PART_ID='water drops', K_FACTOR=2.5, OPERATING_PRESSURE=1.,
      PRESSURE_RAMP='PR', PARTICLE_VELOCITY=2., SPRAY_ANGLE= 0.,60. /

&RAMP ID='PR',   T= 1., F=16. /
&RAMP ID='PR',   T= 2., F=4. /
&RAMP ID='PR',   T= 3., F=1.778 /
&RAMP ID='PR',   T= 4., F=1. /
\end{lstlisting}
The water is tracked using a device measuring the accumulated mass per unit area, integrated over the total floor area. The total mass of water should increase from zero to 10~kg in 60~s. A comparison of the FDS prediction and this analytical result is shown in Fig.~\ref{flow_rate_fig}. The slight delay of the FDS result is caused by the time it takes from the droplets to fall down on the floor.

\begin{figure}[ht]
\begin{tabular*}{\textwidth}{lr}
\includegraphics[width=3.2in]{SCRIPT_FIGURES/flow_rate_open_nozzles} &
\includegraphics[width=3.2in]{SCRIPT_FIGURES/flow_rate_water_mass}
\end{tabular*}
\caption[Results of the {\ct flow\_rate} test case]{Output of the {\ct flow\_rate} test case.}
\label{flow_rate_fig}
\end{figure}

\subsection{Special Topic: Specified Entrainment (Velocity Patch)}
\label{info:velocity_patch}

The details of the sprinkler head geometry and spray atomization are practically impossible to resolve in a fire calculation.  As a result, the local gas phase entrainment by the sprinkler is difficult to predict.  As an alternative, it is possible to specify the local gas velocity in the vicinity of the sprinkler nozzle.  The {\ct PROP} line may be used to specify a polynomial function for a specific velocity component and this function may be ``patched'' into the flow field using a device.  This device is given the quantity {\ct 'VELOCITY PATCH'} and is initially inactive.  The velocity patch must be activated with a separate control device, as discussed in Section \ref{info:basic_control}.  You specify the local region for the velocity patch using {\ct XB} for the device.  The polynomial is defined as a second-order Taylor expansion about the point {\ct XYZ} (the default value of {\ct XYZ} is the center of {\ct XB}).  FDS then uses an immersed boundary method to force the local velocity component to satisfy the polynomial.  The polynomial is specified by the coefficients {\ct P0}, {\ct PX(1\!:\!3)}, and {\ct PXX(1\!:\!3,1\!:\!3)}, which represent, respectively, the value of the $k$th velocity component, the first derivatives, and the second derivatives at point {\ct XYZ}.  Note that the first derivatives are represented by a three component array and the second derivatives are represented by a symmetric $3 \times 3$ array---only the upper triangular part needs to be specified.  The polynomial is given by (note that summation of repeated indices is implied):
\begin{equation}
u_k(\mathbf{r}) = \underbrace{(u_k)_0}_{\mbox{\ct P0}} \,\,+\,\, r_i \underbrace{\left( \frac{\partial u_k}{\partial x_i} \right)_{\!\!\!0}}_{\mbox{\ct PX(1\!:\!3)}} \,\,+\,\,\frac{ r_i r_j}{2} \underbrace{\left(\frac{\partial^2 u_k}{\partial x_i \partial x_j}\right)_{\!\!\!0}}_{\mbox{\ct PXX(1\!:\!3,1\!:\!3)}}
\end{equation}
The vector $\mathbf{r}$ is the position of the velocity storage location relative to the point {\ct XYZ}.  The specific velocity component is specified on {\ct PROP} by the integer {\ct VELOCITY\_COMPONENT}.  Below we provide an example set of {\ct PROP} and {\ct DEVC} lines to specify a parabolic profile for the vertical component of velocity.
\begin{lstlisting}
&PROP ID='p1', VELOCITY_COMPONENT=3, P0=-1,PXX(1,1)=5,PXX(2,2)=5 /
&DEVC XB=-.1,.1,-.1,.1,.9,.95, QUANTITY='VELOCITY PATCH',PROP_ID='p1', DEVC_ID='t1'/
&DEVC ID='t1', XYZ=0,0,.9, QUANTITY='TIME', SETPOINT=10/
\end{lstlisting}
In this example, a velocity patch is activated at 10 s in the simulation.  Any $w$ components of velocity with staggered storage locations within the box {\ct XB=-.1,.1,-.1,.1,.9,.95} will be driven toward the value specified by the polynomial profile {\ct 'p1'}.  You must ensure that the device box encompasses the staggered storage locations (see the theory manual \cite{FDS_Math_Guide} for a discussion on the face-centered velocity storage locations).

\subsection{Heat Detectors}
\label{info:heat_detectors}

{\ct QUANTITY='LINK TEMPERATURE'} defines a heat detector, which uses essentially the same activation algorithm as a sprinkler, without the water spray.
\begin{lstlisting}
&DEVC ID='HD_66', PROP_ID='Acme Heat', XYZ=2.3,4.6,3.4 /
&PROP ID='Acme Heat', QUANTITY='LINK TEMPERATURE', RTI=132., ACTIVATION_TEMPERATURE=74. /
\end{lstlisting}
Like a sprinkler, {\ct RTI} is the Response Time Index in units of $\sqrt{\hbox{m}\cdot \hbox{s}}$. {\ct ACTIVATION\_TEMPERATURE} is the link activation temperature in degrees C (Default 74~$^\circ$C). {\ct INITIAL\_TEMPERATURE} is the initial temperature of the link in units of $^\circ$C (Default {\ct TMPA}).



\subsection{Smoke Detectors}
\label{info:smoke_detector}

A smoke detector is defined in the input file with an entry similar to:
\begin{lstlisting}
&DEVC ID='SD_29', PROP_ID='Acme Smoke Detector', XYZ=2.3,4.6,3.4 /
&PROP ID='Acme Smoke Detector', QUANTITY='CHAMBER OBSCURATION', LENGTH=1.8,
      ACTIVATION_OBSCURATION=3.24 /
\end{lstlisting}
for the single parameter Heskestad model. Note that a {\ct PROP} line is mandatory for a smoke detector, in which case the {\ct DEVC QUANTITY} can be specified on the {\ct PROP} line. For the four parameter Cleary model, use a {\ct PROP} line like:
\begin{lstlisting}
&PROP ID='Acme Smoke Detector I2', QUANTITY='CHAMBER OBSCURATION',
      ALPHA_E=1.8, BETA_E=-1.1, ALPHA_C=1.0, BETA_C=-0.8,
      ACTIVATION_OBSCURATION=3.24 /
\end{lstlisting}
where the two characteristic filling or ``lag'' times are of the form:
\be
   \delta t_e = \alpha_e u^{\beta_e} \quad ; \quad \delta t_c = \alpha_c u^{\beta_c}
\ee
The default detector parameters are for the Heskestad model with a characteristic {\ct LENGTH} of 1.8~m. For the Cleary model, the {\ct ALPHA}s and {\ct BETA}s must all be listed explicitly. Suggested constants for unidentified ionization and photoelectric detectors presented in Table~\ref{tab:sdvalues}. {\ct ACTIVATION\_OBSCURATION} is the threshold value in units of \%/m. The threshold can be set according to the setting commonly provided by the manufacturer. The default setting\footnote{Note that the conversion of obscuration from units of \%/ft to \%/m is given by:
\be
   O[\text{\%/m}] = \left[ 1 - \left( 1 - \frac{O[\text{\%/ft}]}{100} \right)^{3.28} \right] \times 100
\ee
} is 3.24~\%/m (1~\%/ft).

\begin{table}[ht]
\caption[Suggested values for smoke detector model]{Suggested values for smoke detector model~\cite{Cleary:IAFSS6}. See Ref.~\cite{SFPE} for others.}
\vspace{0.1in}
\label{tab:sdvalues}
\begin{center}
\begin{tabular}{|l||c|c|c|c|}
\hline
Detector                      & $\alpha_e$  &  $\beta_e$   &  $\alpha_c, \; L$   &  $\beta_c$  \\ \hline \hline
Cleary Ionization    I1       & 2.5         & -0.7         &  0.8                &  -0.9      \\ \hline
Cleary Ionization    I2       & 1.8         & -1.1         &  1.0                &  -0.8      \\ \hline
Cleary Photoelectric P1       & 1.8         & -1.0         &  1.0                &  -0.8      \\ \hline
Cleary Photoelectric P2       & 1.8         & -0.8         &  0.8                &  -0.8      \\ \hline
Heskestad Ionization          & ---         & ---          &  1.8                &  ---       \\ \hline\end{tabular}
\end{center}
\end{table}

\subsubsection{Defining Smoke}
\label{info:alternative_smoke}

By default, FDS assumes that the smoke from a fire is generated in direct proportion to the heat release rate. A value of {\ct SOOT\_YIELD=0.01} on the {\ct REAC} line means that the smoke generation rate is 0.01 of the fuel burning rate. The ``smoke'' in this case is not explicitly tracked by FDS, but rather is assumed to be a function of the combustion products lumped species.

Suppose, however, that you want to define your own ``smoke'' and that you want to specify its production rate independently of the HRR (or even in lieu of an actual fire, like a smoldering source). You might also want to define a mass extinction coefficient for the smoke and an assumed molecular weight (as it will be tracked like a gas species). Finally, you also want to visualize the smoke using the {\ct SMOKE3D} feature in Smokeview. Use the following lines:
\begin{lstlisting}
&SPEC ID='MY SMOKE', MW=29., MASS_EXTINCTION_COEFFICIENT=8700. /
&SURF ID='SMOLDER', TMP_FRONT=1000., MASS_FLUX(1)=0.0001, SPEC_ID='MY SMOKE', COLOR='RED' /
&VENT XB=0.6,1.0,0.3,0.7,0.0,0.0, SURF_ID='SMOLDER' /

&PROP ID='Acme Smoke', QUANTITY='CHAMBER OBSCURATION', SPEC_ID='MY SMOKE' /
&DEVC XYZ=1.00,0.50,0.95, PROP_ID='Acme Smoke', ID='smoke_1' /

&DUMP SMOKE3D_SPEC_ID='MY SMOKE' /
\end{lstlisting}
The same smoke detector model is used that was described above, but now, the species {\ct 'MY SMOKE'} is used in the algorithm, rather than that associated with the lumped species. Note that your species will not participate in the radiation calculation. It will merely serve as a surrogate for smoke.



\subsection{Beam Detection Systems}
\label{info:beam_detector}

A beam detector can be defined by specifying the endpoints, {\ct (x1,y1,z1) and (x2,y2,z2)}, of the beam and the total percent obscuration at which the detector activates.  The two endpoints must lie in the same mesh.  FDS determines which mesh cells lie along the linear path defined by the two endpoints.  The beam detector response is evaluated as
\be
  \hbox{Obscuration}  = \left(1 - \exp \left( -K_{\rm m} \sum_{i=1}^N {\rho_{{\rm s},i}\; \Delta x_i} \right)  \right) \times 100  \; \; \hbox{\%}
\ee
where $i$ is a mesh cell along the path of the beam, $\rho_{{\rm s},i}$ is the soot density of the mesh cell, $ \Delta x_i$ is the distance within the mesh cell that is traversed by the beam, and $K_{\rm m}$ is the mass extinction coefficient. The line in the input file has the form:
\begin{lstlisting}
&DEVC XB=x1,x2,y1,y2,z1,z2, QUANTITY='PATH OBSCURATION', ID='beam1', SETPOINT=33.0 /
\end{lstlisting}
A similar {\ct QUANTITY} is {\ct 'TRANSMISSION'} which is given by the following expression:
\be
  \hbox{Transmission}  = \exp \left( -K_{\rm m} \frac{L_0}{L} \sum_{i=1}^N {\rho_{{\rm s},i}\; \Delta x_i} \right)  \times 100  \; \; \hbox{\%/m}
\ee
Note that the transmission is given in units of \%/m rather than \% like obscuration. $L$ is the total path length of the beam, and $L_0$ is the reference dimension of 1~m.



\subsubsection{Example Case: A Beam Detector}

A 10~m $\times$ 10~m $\times$ 4~m compartment is filled with smoke from burning propane, represented as 0.006~kg/kg of the lumped species variable, {\ct PRODUCTS}. The soot yield is specified as 0.01~kg/kg, resulting in a uniform soot density of 71.9~mg/m$^3$. Using the default mass extinction coefficient of 8700~m$^2$/kg, the optical depth is calculated to be 0.626~\si{m^{-1}}.  The compartment has a series of obstructions located at increasing distance from the front in increments of 1~m.  The correlation for the output quantity {\ct VISIBILITY}, Eq.~(\ref{vis}), produces a visibility distance of 4.8~m. When viewing the smoke levels with Smokeview, you should just barely see the fifth obstacle which is at a distance of 5~m from the front of the compartment. If this is the case, Smokeview is properly displaying the obscuration of the smoke.  Three beam detectors are also placed in the compartment.  These all have a pathlength of 10~m, but are at different orientations within the compartment. Using the optical depth of 0.626~\si{m^{-1}} and the path length of 10~m, the expected total obscuration is 99.81~\%, which is the result computed by FDS for each of the three detectors.

Note that this case uses 8 meshes to span the computational domain, and the beams are permitted to pass from one mesh to another.

\begin{figure}[ht]
\begin{center}
\includegraphics[width=5.2in]{SCRIPT_FIGURES/beam_detector_nosmoke}
\includegraphics[width=5.2in]{SCRIPT_FIGURES/beam_detector_smoke}
\end{center}
\caption[Results of the {\ct beam\_detector} test case]{Output of the {\ct beam\_detector} test case.}
\label{beam_detector}
\end{figure}


\subsection{Aspiration Detection Systems}
\label{info:aspiration_detector}

An aspiration detection system groups together a series of smoke measurement devices. An aspiration system consists of a sampling pipe network that draws air from a series of locations to a central point where an obscuration measurement is made.  To define such a system in FDS, you must provide the sampling locations, sampling flow rates, the transport time from each sampling location, and if an alarm output is desired, the overall obscuration ``setpoint.''  One or more {\ct DEVC} inputs are used to specify details of the sampling locations, and one additional input is used to specify the central detector:
\begin{lstlisting}
&DEVC XYZ=..., QUANTITY='DENSITY', SPEC_ID='SOOT', ID='soot1', DEVC_ID='asp1',
      FLOWRATE=0.1, DELAY=20 /
&DEVC XYZ=..., QUANTITY='DENSITY', SPEC_ID='SOOT', ID='soot2', DEVC_ID='asp1',
      FLOWRATE=0.2, DELAY=10 /
 ...
&DEVC XYZ=..., QUANTITY='DENSITY', SPEC_ID='SOOT', ID='sootN', DEVC_ID='asp1',
      FLOWRATE=0.3, DELAY=30 /
&DEVC XYZ=..., QUANTITY='ASPIRATION', ID='asp1', BYPASS_FLOWRATE=0.4,
      SETPOINT=0.02 /
\end{lstlisting}
where the {\ct DEVC\_ID} is used at each sampling point to reference the central detector, {\ct FLOWRATE} is the gas flow rate in kg/s, {\ct DELAY} is the transport time (in seconds) from the sampling location to the central detector, {\ct BYPASS\_FLOWRATE} is the flow rate in kg/s of any air drawn into the system from outside the computational
domain (accounts for portions of the sampling network lying outside the domain defined by the {\ct MESH} inputs), and {\ct SETPOINT} is the alarm threshold obscuration in units of \%/m. The output of the aspiration system is computed as
\be
  \hbox{Obscuration}  = \left(1 - \exp \left( -K_{\rm m} \frac {\sum_{i=1}^N {\rho_{{\rm s},i}( t-t_{{\rm d},i}) \; \dm_i}} {\sum_{i=1}^N{ \dm_i} } \right)  \right) \times 100  \; \; \hbox{\%/m}
\ee
where $\dm_i$ is the mass {\ct FLOWRATE} at sampling location $i$, $\rho_{{\rm s},i}( t-t_{{\rm d},i})$ is the soot density at sampling location $i$, $t_{{\rm d},i}$~s prior ({\ct DELAY}) to the current time $t$, and $K_{\rm m}$ is the {\ct MASS\_EXTINCTION\_COEFFICIENT} associated with visible light.

Note that FDS doesn't actually remove gas from the computational domain based upon the {\ct FLOWRATE}; the {\ct FLOWRATE} is just a weighting factor.

\subsubsection{Example Case: aspiration\_detector}
\label{aspiration_detector}

A cubical compartment, 2~m on a side has a three sampling location aspiration system.  The three locations have equal flow rates of 0.3~kg/s, and transport times of 50, 100, and 150~s, respectively.  No bypass flow rate is specified for the aspiration detector.  Combustion products are forced into the bottom of the compartment at a rate of 1~kg/s. The {\ct SOOT\_YIELD=0.001}. Mass is removed from the top of the compartment at a rate of 1~kg/s. The aspiration detector shows an increasing obscuration over time.  There is a delay of slightly over 50~s in the initial increase which results from the 50~s transport time for the first sampling location plus a short period of time to transport the combustion products to the sampling location.  The detector response has three plateaus that result from the delay times of the sampling locations.  The sampling points are co-located, so each plateau represents an additional one third of the soot being transported to the detector.  The soot density at the sampling point is $7.1 \times 10^{-5}$~kg/m$^3$.  Using this value the plateaus are computed as 18~\%, 33.2~\%, and 45.7~\%, as seen in Fig.~\ref{aspiration_detector_fig}.

\begin{figure}[ht]
\begin{center}
\includegraphics[height=2.2in]{SCRIPT_FIGURES/aspiration_detector}
\end{center}
\caption[Results of the {\ct aspiration\_detector} test case]{Output of {\ct aspiration\_detector} test case.}
\label{aspiration_detector_fig}
\end{figure}



\section{Basic Control Logic}
\label{info:basic_control}

Devices can be used to control various actions, like creating and removing obstructions, or activating and deactivating
fans and vents. Every device has an associated {\ct QUANTITY}, whether it is included directly on the {\ct DEVC} line or
indirectly on the optional {\ct PROP} line. Using the {\ct DEVC} parameter {\ct SETPOINT}, you can trigger an action to
occur when the {\ct QUANTITY} value passes above, or below, the given {\ct SETPOINT}.
The following parameters dictate how a device will control something:
\begin{description}
\item[{\ct SETPOINT}] The value of the device at which its state changes.  For a detection type of device (e.g., heat or smoke) this value is taken from the device's {\ct PROP} inputs and need not be specified on the {\ct DEVC} line.
\item[{\ct TRIP\_DIRECTION}] A positive integer means the device will change from its {\ct INITIAL\_STATE} when the value of the device is greater than the {\ct SETPOINT} and be equal to the {\ct INITIAL\_STATE} when the value is less than the {\ct SETPOINT}. A negative integer has the opposite behavior. The device will change from its {\ct INITIAL\_STATE} when the value of the device is less than the {\ct SETPOINT} and be equal to the {\ct INITIAL\_STATE} when the value is greater than the {\ct SETPOINT}. The default value is +1.
\item[{\ct LATCH}] If this logical value is set to {\ct .TRUE.} the device will only change state once. The default value is {\ct .TRUE.}.
\item[{\ct INITIAL\_STATE}] This logical value is the initial state of the device. The default value is {\ct .FALSE.}. For example, if an obstruction associated with the device is to disappear, set {\ct INITIAL\_STATE=.TRUE.}.
\end{description}
If you desire to control FDS using more complex logic than can be provided
by the use of a single device and its setpoint, control functions can be specified using the {\ct CTRL} input.
See Section \ref{info:CTRL} for more on {\ct CTRL} functions.
The simplest example of a device is just a timer:
\begin{lstlisting}
&DEVC XYZ=1.2,3.4,5.6, ID='my clock', QUANTITY='TIME', SETPOINT=30. /
\end{lstlisting}
Anything associated with the device via the parameter, {\ct DEVC\_ID='my clock'}, will change its state at 30~s. For example, if the text were added to an {\ct OBST} line, that obstruction would change from its {\ct INITIAL\_STATE} of {\ct .FALSE.} to {\ct .TRUE.} after 30~s. In other words, it would be created at 30~s instead of at the start of the simulation. This is a simple way to open a door or window.

When using a {\ct DEVC} output to control FDS, the instantaneous value of the {\ct DEVC} is used.  For some {\ct QUANTITY} types, such as {\ct TEMPERATURE}, this output can be very noisy.  To prevent a spurious spike from causing a state change of the {\ct DEVC} you can specify the parameter {\ct SMOOTHING\_FACTOR}.  This is a parameter that can vary between 0 and 1.  It performs an exponential smoothing of the {\ct DEVC} output as follows:
\be
\bar{x}^n=\bar{x}^{n-1} \; \mbox{\ct SMOOTHING\_FACTOR} + x^n \; (1-\mbox{\ct SMOOTHING\_FACTOR})
\ee
where n is the time step, $x$ is the instantaneous device output and $\bar{x}$ is the smoothed output.  The \linebreak[4]{\ct SMOOTHING\_FACTOR} defaults to 0 which means no smoothing is performed.  Note that {\ct SMOOTHING\_FACTOR} only changes the value passed to control functions; it has no effect on the value of the {\ct DEVC} written to the {\ct CHID\_devc.csv} file.

\subsection{Creating and Removing Obstructions}
\label{info:create_remove}

In many fire scenarios, the opening or closing of a door or window can lead to dramatic changes in the course of the fire. Sometimes these actions are taken intentionally, sometimes as a result of the fire. Within the framework of an FDS calculation, these actions are represented by the creation or removal of solid obstacles, or the opening or closing of exterior vents.

Remove or create a solid obstruction by assigning the character string {\ct DEVC\_ID} to indicate the name of a {\ct DEVC} {\ct ID} on the {\ct OBST} line that is to be created or removed.  This will direct FDS to remove or create the obstruction when the device changes state to {\ct .FALSE.} or {\ct .TRUE.}, respectively. For example, the lines
\begin{lstlisting}
&OBST XB=..., DEVC_ID='det2' /
&DEVC XYZ=..., ID='det2', INITIAL_STATE=.TRUE. /
\end{lstlisting}
will cause the given obstruction to be removed when the specified {\ct DEVC} changes state.

Creation or removal at a predetermined time can be performed using a {\ct DEVC} that has {\ct TIME} as its measured quantity. For example, the following instructions will cause the specified {\ct HOLE}s and {\ct OBST}ructions to appear/disappear at the various designated times. These lines are part of the simple test case called {\ct create\_remove.fds}.
\begin{lstlisting}
&OBST XB=0.3,0.4,0.1,0.9,0.1,0.9, COLOR='PURPLE' /
&HOLE XB=0.2,0.4,0.2,0.3,0.2,0.3, COLOR='RED',     DEVC_ID='timer1' /
&HOLE XB=0.2,0.4,0.7,0.8,0.7,0.8, COLOR='GREEN',   DEVC_ID='timer2' /
&OBST XB=0.7,0.8,0.2,0.3,0.2,0.3, COLOR='BLUE',    DEVC_ID='timer3' /
&OBST XB=0.7,0.8,0.6,0.7,0.6,0.7, COLOR='PINK',    DEVC_ID='timer4' /
&OBST XB=0.5,1.0,0.0,1.0,0.0,0.1, COLOR='YELLOW',  DEVC_ID='timer5' /
&HOLE XB=0.7,0.8,0.7,0.8,0.0,0.1, COLOR='BLACK',   DEVC_ID='timer6' /
&HOLE XB=0.7,0.8,0.2,0.3,0.0,0.1, COLOR='GRAY 50', DEVC_ID='timer7' /

&DEVC XYZ=..., ID='timer1', SETPOINT=1., QUANTITY='TIME', INITIAL_STATE=.FALSE. /
&DEVC XYZ=..., ID='timer2', SETPOINT=2., QUANTITY='TIME', INITIAL_STATE=.TRUE.  /
&DEVC XYZ=..., ID='timer3', SETPOINT=3., QUANTITY='TIME', INITIAL_STATE=.FALSE. /
&DEVC XYZ=..., ID='timer4', SETPOINT=4., QUANTITY='TIME', INITIAL_STATE=.TRUE.  /
&DEVC XYZ=..., ID='timer5', SETPOINT=5., QUANTITY='TIME', INITIAL_STATE=.FALSE. /
&DEVC XYZ=..., ID='timer6', SETPOINT=6., QUANTITY='TIME', INITIAL_STATE=.TRUE.  /
&DEVC XYZ=..., ID='timer7', SETPOINT=6., QUANTITY='TIME', INITIAL_STATE=.FALSE. /
\end{lstlisting}
At the start of the simulation, the purple obstruction is present with a red block embedded in it. This red block is actually a {\ct HOLE} whose initial state is {\ct .FALSE.}, i.e., the hole is filled. Also at the start of the simulation, there is a pink obstruction that is visible. At 1~s the red block disappears. At 2~s the empty hole in the purple obstruction is filled with a green block. This hole was initially true, i.e. empty.  The blue obstruction appears at 3~s because its initial state is false, meaning that it does not exist initially. The pink obstruction disappears at 4~s because its initial state is true and this state changes at 4~s. At 5~s a yellow obstruction appears with one empty hole and one embedded gray block.  At 6~s the gray block disappears because it is a hole that was initially false and therefore was filled with the gray block when its parent obstruction (yellow) was created.  Also at 6~s the hole originally present in the yellow obstruction is filled with a black block because it was a hole that was initially empty and then filled when its {\ct DEVC} changed state.  {\em You should always try a simple example first before embarking on a complicated creation/removal scheme for obstructions and holes.}

To learn how to create and remove obstructions multiple times, see Section~\ref{info:CUSTOM} for information about the custom control feature.



\subsection{Activating and Deactivating Vents}
\label{info:activate_deactivate}

When a device or control function is applied to a {\ct VENT}, the purpose is to either activate or deactivate any time ramp associated with the {\ct VENT} via its {\ct DEVC\_ID}. For example, to control a fan, do the following:
\begin{lstlisting}
&SURF ID='FAN', VOLUME_FLOW=5. /
&VENT XB=..., SURF_ID='FAN', DEVC_ID='det2' /
&DEVC ID='det2', XYZ=..., QUANTITY='TIME', SETPOINT=30., INITIAL_STATE=.FALSE. /
\end{lstlisting}
Note that at 30~s, the ``state'' of the {\ct 'FAN'} changes from {\ct .FALSE.} to {\ct .TRUE.}, or more simply, the {\ct 'FAN'} turns on. Since there is no explicit time function associated with the {\ct 'FAN'}, the default 1~s ramp-up will begin at 30~s instead of at 0~s. If {\ct INITIAL\_STATE=.TRUE.}, then the fan should turn off at 30~s. Essentially, ``activation'' of a {\ct VENT} causes all associated time functions to be delayed until the device {\ct SETPOINT} is reached. ``Deactivation'' of a {\ct VENT} turns off all time functions. Usually this means that the parameters on the {\ct SURF} line are all nullified, so it is a good idea to check the functionality with a simple example.

A {\ct 'MIRROR'} or {\ct 'OPEN'} {\ct VENT} should not be activated or deactivated. You can, however, place an obstruction in front of an {\ct 'OPEN'} {\ct VENT} and then create it or remove it to model the closing or opening of a door or window.

There are sometimes circumstances when you might want to create or remove obstructions that have {\ct VENT}s attached. If the obstructions overlap, there can be confusion as to which {\ct VENT} goes with which {\ct OBST}. If you come across a situation like this, give the {\ct OBST} an {\ct ID} and assign this {\ct OBST\_ID} on the {\ct VENT} line.



\section{Advanced Control Functions: The \texorpdfstring{{\tt CTRL}}{CTRL} Namelist Group}
\label{info:CTRL}

There are many systems whose functionality cannot be described by a simple device with a single ``setpoint.'' Consider for example, a typical HVAC system used for heat.  It is controlled by a thermostat that is given a temperature setpoint. The system turns on when the temperature goes below the setpoint by some amount and then turns off when the temperature rises above that same setpoint by some amount. This behavior cannot be defined by merely specifying a single setpoint. You must also define the range or ``deadband'' around the setpoint, and whether an increasing or decreasing temperature activates the system.  For the HVAC example, crossing the lower edge of the deadband activates heating; crossing the upper edge deactivates heating.  These more complicated behaviors can be modeled in FDS using {\ct CTRL}s.  The following parameters dictate how a control function will behave:
\begin{description}
\item[{\ct ID}] A name for the control function that is unique over all control functions.
\item[{\ct FUNCTION\_TYPE}] The type of control function.  The possible types are shown in Table~\ref{tab:funcvalues}.
\item[{\ct INPUT\_ID}] A list of {\ct DEVC} or {\ct CTRL} {\ct ID}s that are the inputs to the control function.  Up to forty inputs can be specified.  If a {\ct DEVC} or {\ct CTRL} is being used as an {\ct INPUT\_ID} for a control function, then it must have a unique {\ct ID} over both devices and control functions.  Additionally, a control function cannot be used as an input for itself.
\item[{\ct SETPOINT}] The value of the control function at which its state changes. This is only appropriate for functions that return numerical values.
\item[{\ct TRIP\_DIRECTION}] A positive integer means the control function will change state when its value increases
past the setpoint and a negative integer means the control function will change state
when its value decreases past the setpoint.  The default value is +1.
\item[{\ct LATCH}] If this logical value is set to {\ct .TRUE.} the control function will only change state once.
The default value is {\ct .TRUE.}.
\item[{\ct INITIAL\_STATE}] This logical value is the initial state of the control function. The default value
is {\ct .FALSE.} For example, if an obstruction associated with the control function is to disappear, set {\ct INITIAL\_STATE} to {\ct .TRUE.}
\end{description}
For any object for which a {\ct DEVC\_ID} can be specified (such as {\ct OBST} or {\ct VENT}), a {\ct CTRL\_ID} can be
specified instead.

\begin{table}[h!]
\caption[Control function types]{Control function types.}
\label{tab:funcvalues}
\begin{center}
\begin{tabular}{|l||l|}
\hline
{\ct FUNCTION\_TYPE}              & Purpose   \\ \hline \hline
{\ct ANY}                         & Changes state if \underline{any} {\ct INPUT}s are {\ct .TRUE.}  \\ \hline
{\ct ALL}                         & Changes state if \underline{all} {\ct INPUT}s are {\ct .TRUE.}  \\ \hline
{\ct ONLY}                        & Changes state if and \underline{only} if {\ct N} {\ct INPUT}s are {\ct .TRUE.}  \\ \hline
{\ct AT\_LEAST}                   & Changes state if \underline{at least} {\ct N} {\ct INPUT}s are {\ct .TRUE.}  \\ \hline
%{\ct CYCLING}                     & Changes state in a cyclical manner once its sole {\ct INPUT} is {\ct .TRUE.} \\ \hline
{\ct TIME\_DELAY}                 & Changes state {\ct DELAY} s after {\ct INPUT} becomes {\ct .TRUE.} \\ \hline
{\ct CUSTOM}                      & Changes state based on evaluating a {\ct RAMP} of the function's input \\ \hline
{\ct DEADBAND}                    & Behaves like a thermostat  \\ \hline
{\ct KILL}                        & Terminates code execution if {\ct INPUT} is {\ct .TRUE.}  \\ \hline
{\ct RESTART}                     & Dumps restart files if {\ct INPUT} is {\ct .TRUE.} \\ \hline
{\ct SUM}                         & Sums the outputs of the {\ct INPUT}s \\ \hline
{\ct SUBTRACT}                    & Subtracts the second {\ct INPUT} from the first \\ \hline
{\ct MULTIPLY}                    & Multiplies the {\ct INPUT}s \\ \hline
{\ct DIVIDE}                      & Divides the first {\ct INPUT} by the second \\ \hline
{\ct POWER}                       & The first {\ct INPUT} to the power of the second \\ \hline
{\ct EXP}                         & The exponential of the {\ct INPUT} \\ \hline
{\ct LOG}                         & The natural logarithm of the {\ct INPUT} \\ \hline
{\ct COS}                         & The cosine of the {\ct INPUT} \\ \hline
{\ct SIN}                         & The sine of the {\ct INPUT} \\ \hline
{\ct ACOS}                        & The arccosine of the {\ct INPUT} \\ \hline
{\ct ASIN}                        & The arcsine of the {\ct INPUT} \\ \hline
{\ct MAX}                         & Maximum value of the {\ct INPUT}s \\ \hline
{\ct MIN}                         & Minimum value of the {\ct INPUT}s \\ \hline
{\ct PID}                         & A Proportional-Integral-Derivative control for the {\ct INPUT}\\ \hline
\end{tabular}
\end{center}
\end{table}

If you want to design a system of controls and devices that involves multiple changes of state, include the attribute {\ct LATCH=.FALSE.} on the relevant {\ct DEVC} or {\ct CTRL} input lines. By default, devices and controls may only change state once, like a sprinkler activating or smoke detector alarming. {\ct LATCH} is {\ct .TRUE.} by default for both devices and controls.

If you want a {\ct DEVC} to operate based on the logical state of a {\ct CTRL}, set {\ct QUANTITY} equal to {\ct 'CONTROL'} and set the {\ct CTRL\_ID} on the {\ct DEVC} input to the {\ct ID} of the control function.

The output value of numerical control function is defined by a {\ct DEVC} line with {\ct QUANTITY} set equal to {\ct 'CONTROL VALUE'} and {\ct CTRL\_ID} set equal to the {\ct ID} of the control function.  You can then use {\ct SETPOINT} to have the {\ct DEVC} operate a particular output value of the control function.


\subsection{Control Functions: \texorpdfstring{{\tt ANY}}{ANY}, \texorpdfstring{{\tt ALL}}{ALL}, \texorpdfstring{{\tt ONLY}}{ONLY}, and
\texorpdfstring{{\tt AT\_LEAST}}{AT\_LEAST}}

\label{info:FUNCTION_TYPE}

Suppose you want an obstruction to be removed (a door is opened, for example) after any of four smoke detectors in a room has activated. Use input lines of the form:
\begin{lstlisting}
&OBST XB=..., SURF_ID='...', CTRL_ID='SD' /

&DEVC XYZ=1,1,3, PROP_ID='Acme Smoker', ID='SD_1' /
&DEVC XYZ=1,4,3, PROP_ID='Acme Smoker', ID='SD_2' /
&DEVC XYZ=4,1,3, PROP_ID='Acme Smoker', ID='SD_3' /
&DEVC XYZ=4,4,3, PROP_ID='Acme Smoker', ID='SD_4' /
&CTRL ID='SD', FUNCTION_TYPE='ANY', INPUT_ID='SD_1','SD_2','SD_3','SD_4',
      INITIAL_STATE=.TRUE. /
\end{lstlisting}
The {\ct INITIAL\_STATE} of the control function {\ct SD} is {\ct .TRUE.}, meaning that the obstruction exists initially. The ``change of state'' means that the obstruction is removed when \underline{any} smoke detector alarms.  By default, the {\ct INITIAL\_STATE} of the control function {\ct SD} is {\ct .FALSE.}, meaning that the obstruction does not exist initially.

Suppose that now you want the obstruction to be created (a door is closed, for example) after all four smoke detectors in a room have activated. Use a control line of the form:
\begin{lstlisting}
&CTRL ID='SD', FUNCTION_TYPE='ALL', INPUT_ID='SD_1','SD_2','SD_3','SD_4' /
\end{lstlisting}
The control functions {\ct AT\_LEAST} and {\ct ONLY} are generalizations of {\ct ANY} and {\ct ALL}. For example,
\begin{lstlisting}
&CTRL ID='SD', FUNCTION_TYPE='AT_LEAST', N=3, INPUT_ID='SD_1','SD_2','SD_3','SD_4' /
\end{lstlisting}
changes the state from {\ct .FALSE.} to {\ct .TRUE.} when \underline{at least} 3 detectors activate. Note that in this example, and the example below, the parameter {\ct N} is used to specify the number of activated devices required for the conditions of the control function to be satisfied. The control function,
\begin{lstlisting}
&CTRL ID='SD', FUNCTION_TYPE='ONLY', N=3, INPUT_ID='SD_1','SD_2','SD_3','SD_4' /
\end{lstlisting}
changes the state from {\ct .FALSE.} to {\ct .TRUE.} when 3, and \underline{only} 3, detectors activate.


\subsection{Control Function: \texorpdfstring{{\tt TIME\_DELAY}}{TIME\_DELAY}}

\label{info:TIME_DELAY}

The {\ct TIME\_DELAY} control function starts a timer of length {\ct DELAY} when its input changes state. When the timer expires, the {\ct TIME\_DELAY} control function will change state. Note, that the timer starts at each change in state of the input; therefore, if the input changes state a second time before the first timer ends, the timer will get reset. This function enables FDS to model time delays between when a device activates and when some other action occurs, like in a dry pipe sprinkler system.
\begin{lstlisting}
&DEVC XYZ=2,2,3, PROP_ID='Acme Sprinkler_link', QUANTITY='LINK TEMPERATURE',
      ID='Spk_29_link' /
&DEVC XYZ=2,2,3, PROP_ID='Acme Sprinkler', QUANTITY='CONTROL', ID='Spk_29',
      CTRL_ID='dry pipe' /
&CTRL ID='dry pipe', FUNCTION_TYPE='TIME_DELAY', INPUT_ID='Spk_29_link', DELAY=30. /
\end{lstlisting}
This relationship between a sprinkler and its pipes means that the sprinkler spray is controlled (in this case delayed) by the {\ct 'dry pipe'}, which adds 30~s to the activation time of {\ct Spk\_29}, measured by  {\ct Spk\_29\_link}, before water can flow out of the head.


\subsection{Control Function: \texorpdfstring{{\tt DEADBAND}}{DEADBAND}}
\label{info:DEADBAND}

This control function behaves like an HVAC thermostat.  It can operate in one of two modes analogous to heating or cooling. The function is provided with an {\ct INPUT\_ID} which is the {\ct DEVC} whose value is used by the function, an upper and lower {\ct SETPOINT}, and the mode of operation by {\ct ON\_BOUND}.  If  {\ct ON\_BOUND='LOWER'}, the function changes state from its {\ct INITIAL\_STATE} when the value of the {\ct INPUT\_ID} drops below the lower value in {\ct SETPOINT} and reverts when it increases past the upper value, i.e., like a heating system. The reverse will occur if {\ct ON\_BOUND='UPPER'}, i.e., a cooling system.

For an HVAC system, the following lines of input would set up a simple thermostat:
\begin{lstlisting}
&SURF ID='FAN', TMP_FRONT=40., VOLUME_FLOW=-1. /
&VENT XB=-0.3,0.3,-0.3,0.3,0.0,0.0, SURF_ID='FAN', CTRL_ID='thermostat' /
&DEVC ID='TC', XYZ=2.4,5.7,3.6, QUANTITY='TEMPERATURE' /
&CTRL ID='thermostat', FUNCTION_TYPE='DEADBAND', INPUT_ID='TC',
      ON_BOUND='LOWER', SETPOINT=23.,27., LATCH=.FALSE./
\end{lstlisting}
Here, we want to control the {\ct VENT} that simulates the {\ct FAN}, which blows hot air into the room. A {\ct DEVC} called {\ct TC} is positioned in the room to measure the {\ct TEMPERATURE}. The {\ct thermostat} uses a {\ct SETPOINT} to turn on the {\ct FAN} when the temperature falls below 23~$^\circ$C ({\ct ON\_BOUND='LOWER'}) and it turns off when the temperature rises above 27~$^\circ$C.

Note that a deadband controller needs to have {\ct LATCH} set to {\ct .FALSE.}


\subsection{Control Function: \texorpdfstring{{\tt RESTART} and {\tt KILL}} {RESTARTKILL} }

There are times when you might only want to run a simulation until some goal is reached, or you might want to create some baseline condition and then run multiple permutations of that baseline. For example, you might want to run a series of simulations where different mitigation strategies are tested once a detector alarms. Using the {\ct RESTART} control function, you can cause a restart file to be created once a desired condition is met.  The simulation can continue and the restart files can be copied to have the job identifying string, {\ct CHID}, of the various permutations (providing of course that the usual restrictions on the use of restart files are followed). For example, the lines
\begin{lstlisting}
&DEVC ID='temp', QUANTITY='TEMPERATURE', SETPOINT=1000., XYZ=4.5,6.7,3.6 /
&DEVC ID='velo', QUANTITY='VELOCITY', SETPOINT=10., XYZ=4.5,6.7,3.6 /

&CTRL ID='kill', FUNCTION_TYPE='KILL', INPUT_ID='temp' /
&CTRL ID='restart', FUNCTION_TYPE='RESTART', INPUT_ID='velo' /
\end{lstlisting}
will kill the job and output restart files when the temperature at the given point rises above 1000~$^\circ$C; or just force restart files to be output when the velocity at a given point exceeds 10~m/s.



\subsection{Control Function: \texorpdfstring{{\tt CUSTOM}}{CUSTOM} }
\label{info:CUSTOM}

For most of the control function types, the logical (true/false) output of the devices and control functions and the time they last changed state are taken as inputs.  A {\ct CUSTOM} function uses the numerical output of a {\ct DEVC} along with a {\ct RAMP} to determine the output of the function.  When the {\ct RAMP} output for the {\ct DEVC} value is negative, the {\ct CTRL} will have the value of its {\ct INITIAL\_STATE}.  When the {\ct RAMP} output for the {\ct DEVC} value is positive, the {\ct CTRL} will have the opposite value of its {\ct INITIAL\_STATE}. In the case below, the {\ct CUSTOM} control function uses the numerical output of a timer device as its input.  The function returns true (the default value for {\ct INITIAL\_STATE} is {\ct .FALSE.}) when the {\ct F} parameter in the ramp specified with {\ct RAMP\_ID} is a positive value and false when the {\ct RAMP} {\ct F} value is negative. In this case, the control would start false and would switch to true when the timer reaches 60~s.  It would then stay in a true state until the timer reaches 120~s and would then change back to false.


Note that when using control functions the {\ct ID}s assigned to both the {\ct CTRL} and the {\ct DEVC} inputs must be unique across both sets of inputs, i.e., you cannot use the same {\ct ID} for both a control function and a device. You can make a fan operate on a fixed cycle by using a {\ct CUSTOM} control function based on time:
\begin{lstlisting}
&SURF ID='FAN', TMP_FRONT=40., VOLUME_FLOW=-1. /
&VENT XB=-0.3,0.3,-0.3,0.3,0.0,0.0, SURF_ID='FAN', CTRL_ID='cycling timer' /
&DEVC ID='TIMER', XYZ=2.4,5.7,3.6, QUANTITY='TIME' /
&CTRL ID='cycling timer', FUNCTION_TYPE='CUSTOM', INPUT_ID='TIMER', RAMP_ID='cycle' /
&RAMP ID='cycle', T= 59, F=-1 /
&RAMP ID='cycle', T= 61, F= 1 /
&RAMP ID='cycle', T=119, F= 1 /
&RAMP ID='cycle', T=121, F=-1 /
\end{lstlisting}
In the above example the fan will be off initially, turn on at 60~s and then turn off at 120~s.

You can make an obstruction appear and disappear multiple times by using the following lines
\begin{lstlisting}
&OBST XB=..., SURF_ID='whatever', CTRL_ID='cycling timer' /
&DEVC ID='TIMER', XYZ=..., QUANTITY='TIME' /
&CTRL ID='cycling timer', FUNCTION_TYPE='CUSTOM', INPUT_ID='TIMER', RAMP_ID='cycle' /
&RAMP ID='cycle', T=  0, F=-1 /
&RAMP ID='cycle', T= 59, F=-1 /
&RAMP ID='cycle', T= 61, F= 1 /
&RAMP ID='cycle', T=119, F= 1 /
&RAMP ID='cycle', T=121, F=-1 /
\end{lstlisting}
The above will have the obstacle initially removed, then added at 60 s, and removed again at 120 s.

Experiment with these combinations using a simple case before trying a case to make sure that FDS indeed is doing what is intended.

\subsection{Control Function: Math Operations }
\label{info:CONTROL_MATH}

The control functions that perform simple math operations ({\ct SUM},  {\ct SUBTRACT},  {\ct MULTIPLY},  {\ct DIVIDE}, {\ct POWER}, etc.) can have a constant value specified as one of their inputs.  This is done by specifying one of the {\ct INPUT\_ID}s as {\ct 'CONSTANT'} and providing the value using the input {\ct CONSTANT}. For example, the inputs below represent a control function whose state changes when the square of the velocity exceeds 10 (see Section~\ref{info:basic_control} for an explanation of {\ct TRIP\_DIRECTION}).

\begin{lstlisting}
&DEVC ID='SPEED SENSOR', XYZ=..., QUANTITY='VELOCITY' /
&CTRL ID='multiplier', FUNCTION_TYPE='POWER',
      INPUT_ID='SPEED SENSOR','CONSTANT', CONSTANT=2., SETPOINT=10.,
      TRIP_DIRECTION=1 /
\end{lstlisting}


\subsection{Control Function: PID Control Function}
\label{info:CONTROL_PID}

A PID (Proportional Integral Derivative) control function is a commonly used feedback controller for controlling electrical and mechanical systems.  The function computes an error between a process variable and a desired setpoint.  The goal of the PID function is to minimize the error.  A PID control function is computed as
\be u(t) \; = \; K_{\rm p} \, e(t) \; + \; \; K_{\rm i} \int_0^t \! e(t) \, \d t   \; + \; K_{\rm d} \frac{\d e(t)}{\d t}\ee
where $K_{\rm p}$, $K_{\rm i}$, and $K_{\rm d}$ are respectively the {\ct PROPORTIONAL\_GAIN}, the {\ct INTEGRAL\_GAIN}, and the
\linebreak[4]{\ct DIFFERENTIAL\_GAIN}; $e(t)$ is the error given by subtracting the {\ct TARGET\_VALUE} from the {\ct INPUT\_ID}; and $u(t)$ is the output.


\subsubsection{Example Case: using PID for time integration of mass loss rate }
\label{sec:pidintmlr}

The PID controller can be used to time integrate the mass loss from a pyrolyzing surface.  First, use a {\ct DEVC} with {\ct SPATIAL\_STATISTIC='SURFACE INTEGRAL'} as input to the PID controller.  Omit the {\ct TARGET\_VALUE}, which then defaults to 0, and the input becomes the error function, $e(t)$.  Set the {\ct INTEGRAL\_GAIN} to 1 and the other gains to 0.  Then send the PID output to a {\ct DEVC} for a {\ct 'CONTROL VALUE'}.  Here is example syntax:
\begin{lstlisting}
&DEVC ID='MY MLR', XB=..., QUANTITY='BURNING RATE', SURF_ID='s1',
      SPATIAL_STATISTIC='SURFACE INTEGRAL'/
&CTRL ID='MY PID', FUNCTION_TYPE='PID', INPUT_ID='MY MLR',
      PROPORTIONAL_GAIN=0, DIFFERENTIAL_GAIN=0, INTEGRAL_GAIN=1/
&DEVC ID='PYROLYZATE', XYZ=..., QUANTITY='CONTROL VALUE', CTRL_ID='MY PID'/
\end{lstlisting}
Here, the {\ct 'PYROLYZATE'} column of the {\ct \_devc.csv} file will have units of \si{kg}.


\subsection{Combining Control Functions: A Deluge System}

For a deluge sprinkler system, the normally
dry sprinkler pipes are flooded when a detection event occurs. For this example, the detection event is
when two of four smoke detectors alarm.  It takes 30~s to flood the piping network.
The nozzle is a {\ct DEVC} named {\ct 'NOZZLE 1'} controlled by the {\ct CTRL} named {\ct 'nozzle trigger'}.
The nozzle activates when both detection \underline{and} the time delay have occurred.  Note that the {\ct DEVC} is
specified with {\ct QUANTITY='CONTROL'}.

\begin{lstlisting}
&DEVC XYZ=1,1,3, PROP_ID='Acme Smoker', ID='SD_1' /
&DEVC XYZ=1,4,3, PROP_ID='Acme Smoker', ID='SD_2' /
&DEVC XYZ=4,1,3, PROP_ID='Acme Smoker', ID='SD_3' /
&DEVC XYZ=4,4,3, PROP_ID='Acme Smoker', ID='SD_4' /
&DEVC XYZ=2,2,3, PROP_ID='Acme Nozzle', QUANTITY='CONTROL',
      ID='NOZZLE 1', CTRL_ID='nozzle trigger' /

&CTRL ID='nozzle trigger', FUNCTION_TYPE='ALL', INPUT_ID='smokey','delay' /
&CTRL ID='delay', FUNCTION_TYPE='TIME_DELAY', INPUT_ID='smokey', DELAY=30. /
&CTRL ID='smokey', FUNCTION_TYPE='AT_LEAST', N=2, INPUT_ID='SD_1','SD_2','SD_3','SD_4' /
\end{lstlisting}

\subsubsection{Example Case: control\_test\_2 }
\label{control_test_2}

The {\ct control\_test\_2} example demonstrates the use of the mathematical and PID control functions.  Two compartments are defined with the left hand compartment initialized to 20 $^\circ$C and the right hand compartment to 10 $^\circ$C.    Control functions are defined to:

\begin{itemize}
\item Add the temperatures in the two compartments
\item Subtract the right hand compartment temperature from the left hand compartment temperature
\item Multiply the left hand temperature by 0.5
\item Divide the left hand temperature by the right hand temperature
\item Take the square root of the right hand temperature
\item Use the time as input to a PID function with a target value of 5 and $K_p$=-0.5, $K_i$=0.001, and $K_d$=1
\end{itemize}

\begin{lstlisting}
&CTRL ID='Add',FUNCTION_TYPE='SUM',INPUT_ID='LHS Temp','RHS Temp'/
&CTRL ID='Subtract',FUNCTION_TYPE='SUBTRACT',INPUT_ID='RHS Temp','LHS Temp'/
&CTRL ID='Multiply',FUNCTION_TYPE='MULTIPLY',INPUT_ID='LHS Temp','CONSTANT',CONSTANT=0.5/
&CTRL ID='Divide',FUNCTION_TYPE='DIVIDE',INPUT_ID='LHS Temp','RHS Temp'/
&CTRL ID='Power',FUNCTION_TYPE='POWER',INPUT_ID='RHS Temp','CONSTANT',CONSTANT=0.5/
&CTRL ID='PID',FUNCTION_TYPE='PID',INPUT_ID='Time',TARGET_VALUE=5.,
          PROPORTIONAL_GAIN=-0.5,INTEGRAL_GAIN=0.001,DIFFERENTIAL_GAIN=1./
\end{lstlisting}

\noindent Results are shown in Fig.~\ref{control_test_2_fig}.
\begin{figure}[ht]
\centering
\includegraphics[scale=0.55]{SCRIPT_FIGURES/control_test_2}
\caption[Results of the {\ct control\_test\_2} case]{Results of the {\ct control\_test\_2} case.}
\label{control_test_2_fig}
\end{figure}


\subsection{Combining Control Functions: A Dry Pipe Sprinkler System}
\label{info:dry_pipe}

For a dry-pipe sprinkler system, the normally
dry sprinkler pipes are pressurized with gas.  When a link activates in a sprinkler head, the pressure drop allows
water to flow into the pipe network.  For this example it takes 30~s to flood the piping network once a sprinkler link
has activated.  The sequence of events required for operation is first {\ct ANY} of the links must activate which
starts the 30~s {\ct TIME\_DELAY}.  Once the 30~s delay has occurred, each nozzle with an active link, the {\ct ALL}
control functions, will then flow water.

\begin{lstlisting}
&DEVC XYZ=2,2,3, PROP_ID='Acme Sprinkler Link', ID='LINK 1' /
&DEVC XYZ=2,3,3, PROP_ID='Acme Sprinkler Link', ID='LINK 2' /

&PROP ID='Acme Sprinkler Link', QUANTITY='LINK TEMPERATURE',
      ACTIVATION_TEMPERATURE=74., RTI=30./

&DEVC XYZ=2,2,3, PROP_ID='Acme Nozzle', QUANTITY='CONTROL',
      ID='NOZZLE 1', CTRL_ID='nozzle 1 trigger' /
&DEVC XYZ=2,3,3, PROP_ID='Acme Nozzle', QUANTITY='CONTROL',
      ID='NOZZLE 2', CTRL_ID='nozzle 2 trigger' /

&CTRL ID='check links', FUNCTION_TYPE='ANY', INPUT_ID='LINK 1','LINK 2'/
&CTRL ID='delay', FUNCTION_TYPE='TIME_DELAY', INPUT_ID='check links', DELAY=30. /
&CTRL ID='nozzle 1 trigger', FUNCTION_TYPE='ALL', INPUT_ID='delay','LINK 1'/
&CTRL ID='nozzle 2 trigger', FUNCTION_TYPE='ALL', INPUT_ID='delay','LINK 2'/
\end{lstlisting}


\subsection{Example Case: activate\_vents}
\label{activate_vents}

The simple test case called {\ct activate\_vents} demonstrates several of the control functions. Figure~\ref{activate_vents_fig} shows seven differently colored vents that activate at different times, depending on the particular timing or control function.
\begin{figure}[ht]
\begin{tabular*}{\textwidth}{lll}
\includegraphics[width=2.05in]{SCRIPT_FIGURES/activate_vents_5} &
\includegraphics[width=2.05in]{SCRIPT_FIGURES/activate_vents_10} &
\includegraphics[width=2.05in]{SCRIPT_FIGURES/activate_vents_15}
\end{tabular*}
\caption[Snapshots of the {\ct activate\_vents} test case]{Output of the {\ct activate\_vents} test case at 5, 10, and 15~s.}
\label{activate_vents_fig}
\end{figure}




\section{Controlling a \texorpdfstring{{\tt RAMP}}{RAMP}}

\subsection{Changing the Independent variable}
\label{info:RAMPDEVC}

For any user-defined {\ct RAMP}, the normal independent variable, for example time for {\ct RAMP\_V}, can be replaced by the output of a {\ct DEVC}.
This is done by specifying the input {\ct DEVC\_ID} on one of the {\ct RAMP} input lines.  When this is done, the current output of the {\ct DEVC} is used as the independent variable for the {\ct RAMP}.  A {\ct CTRL\_ID} can also be specified as long as the control function outputs a numerical value (i.e., is a mathematical function (Section~\ref{info:CONTROL_MATH}) or a PID function (Section~\ref{info:CONTROL_PID}).
In the following example a blower is ramped from 0~\% flow at 20~$^\circ$C, to 50~\% flow when the temperature exceeds 100~$^\circ$C, and to 100~\% flow when the temperature exceeds 200~$^\circ$C.
This is similar functionality to the {\ct CUSTOM} control function, but it allows for variable response rather than just on or off.

\begin{lstlisting}
&SURF ID='BLOWER', VEL=-2, RAMP_V='BLOWER RAMP' /
&DEVC XYZ=2,3,3, QUANTITY='TEMPERATURE', ID='TEMP DEVC' /
&RAMP ID='BLOWER RAMP', T= 20,F=0.0, DEVC_ID='TEMP DEVC' /
&RAMP ID='BLOWER RAMP', T=100,F=0.5 /
&RAMP ID='BLOWER RAMP', T=200,F=1.0 /
\end{lstlisting}

\subsection{Freezing the Output Value, Example Case: hrr\_freeze}
\label{info:freeze_device}

There are occasions where you may want the value of a {\ct RAMP} to stop updating.  For example, if you are simulating a growing fire in a room with sprinklers, you may wish to stop the fire from growing when a sprinkler over the fire activates.  This type of action can be accomplished by changing the input of the {\ct RAMP} to a {\ct DEVC} (see the previous section) and then giving that {\ct DEVC} either a {\ct NO\_UPDATE\_DEVC\_ID} or a {\ct NO\_UPDATE\_CTRL\_ID}.  When the specified controller changes its state to {\ct .TRUE.} it will cause the {\ct DEVC} to stop updating its value.  Since the {\ct DEVC} is being used as the independent variable to a {\ct RAMP}, the {\ct RAMP} will have its output remain the same.  This is shown in the example below.  A fire is given a linear {\ct RAMP} from 0 to 1000~kW/m$^2$ over 50~s. Rather than using the simulation time, the {\ct RAMP} uses a {\ct DEVC} for the time.  The timer is set to freeze when another {\ct DEVC} measuring time reaches 200~$^\circ$C.  Figure~\ref{freeze_hrr} shows the result of these inputs in the test case {\ct hrr\_freeze} where it can be seen that the pyrolysis rate stops increasing once the gas temperature reaches 200~$^\circ$C.
\begin{lstlisting}
&SURF ID='FIRE', HRRPUA=1000., RAMP_Q='FRAMP', COLOR='ORANGE'/
&RAMP ID='FRAMP', T= 0, F=0, DEVC_ID='FREEZE TIME'/
&RAMP ID='FRAMP', T=50, F=1/
&DEVC XYZ=..., QUANTITY='TEMPERATURE', SETPOINT=200., INITIAL_STATE=.FALSE.,
      ID='TEMP'/
&DEVC XYZ=..., QUANTITY='TIME', NO_UPDATE_DEVC_ID='TEMP', ID='FREEZE TIME'/
\end{lstlisting}

\begin{figure}[ht]
\begin{tabular*}{\textwidth}{lll}
\includegraphics[width=3.0in]{SCRIPT_FIGURES/hrr_freeze_T} &
\includegraphics[width=3.0in]{SCRIPT_FIGURES/hrr_freeze_B} &
\end{tabular*}
\caption[Example of freezing the output of a {\ct RAMP}]{Temperature (left) and burning rate (right) outputs of the {\ct hrr\_freeze} test case.}
\label{freeze_hrr}
\end{figure}

It should be noted that devices are updated sequentially in the order that they are listed in the input file and that devices in different meshes do not share values until the end of a time step.  This means that if the device being frozen is on a different mesh or is listed before the device that freezes it, it will not be frozen until the next time step.


\input{smv_objects.tex}



\chapter{Output}
\label{info:outputdata}

FDS has various types of output files that store computed data. Some of the files are in binary format and intended to be read and rendered by Smokeview. Some of the files are just comma-delimited text files. It is important to remember that you must explicitly declare in the input file most of the FDS output data. A considerable amount of the input file is usually devoted to this.

To visualize the flow patterns better, save planar slices of data, either in the gas or solid phases, by using the {\ct SLCF} (SLiCe File) or {\ct BNDF} (BouNDary File) namelist group. Both of these output formats permit you to animate these quantities in time. For static pictures of the flow field, use the Plot3D output, a format that is used by many CFD programs as a simple way to store specified quantities over the entire mesh at one instant in time. Finally, tracer particles can be injected into the flow field from vents or obstacles, and then viewed in Smokeview. Use the {\ct PART} namelist group to control the injection rate, sampling rate and other parameters associated with particles.


\section{Output Control Parameters: The \texorpdfstring{{\tt DUMP}}{DUMP} Namelist Group}
\label{info:DUMP}

The namelist group {\ct DUMP} contains parameters (Table \ref{tbl:DUMP}) that control the rate at which output files are written, and various other global parameters associated with output files. Its parameters include:
\begin{description}
\item[{\ct NFRAMES}] Number of output dumps per calculation. The default is 1000. Device data, slice data, particle data, isosurface data, 3D smoke data, boundary data, solid phase profile data, and control function data are saved every {\ct (T\_END-T\_BEGIN)/NFRAMES} seconds unless otherwise specified using {\ct DT\_DEVC}, {\ct DT\_SLCF}, {\ct DT\_PART}, {\ct DT\_ISOF}, {\ct DT\_BNDF}, {\ct DT\_PROF}, or {\ct DT\_CTRL}. Note that {\ct DT\_SLCF} controls Smoke3D output. {\ct DT\_HRR} controls the output of heat release rate and associated quantities.
\item[{\ct MASS\_FILE}] If {\ct .TRUE.}, produce an output file listing the total masses of all gas species as a function of time. It is {\ct .FALSE.} by default because the calculation of all gas species in all mesh cells is time-consuming. The parameter {\ct DT\_MASS} controls the frequency of output.
\item[{\ct MAXIMUM\_PARTICLES}] Maximum number of Lagrangian particles that can be included on any mesh at any given time. (Default 1000000)
\item[{\ct SMOKE3D}] If {\ct .FALSE.}, do not produce an animation of the smoke and fire. It is {\ct .TRUE.} by default.
\item[{\ct DT\_PL3D}] The time between Plot3D file output. Note that versions of FDS before 6 output Plot3D files by default. Now, you must specify the interval of output using this parameter. Its default value is 1000000~s, meaning that there is no Plot3D output unless specified.
\item[{\ct FLUSH\_FILE\_BUFFERS}] FDS purges the output file buffers periodically and forces the data to be written out into the respective output files. It does this to make it easier to view the case in Smokeview while it is running. It has been noticed on Windows machines that occasionally a runtime error occurs because of file access problems related to the buffer flushing. If this happens, set this parameter to {\ct .FALSE.}, but be aware that it may not be possible to look at output in Smokeview until after the calculation is finished. You may also set {\ct DT\_FLUSH} to control the frequency of the file flushing. Its default value is the duration of the simulation divided by {\ct NFRAMES}.
\item[{\ct STATUS\_FILES}] If {\ct .TRUE.}, produces an output file {\ct CHID.notready} which is deleted, if the simulation is completed successfully. This file can be used as an error indicator. It is {\ct .FALSE.} by default.
\end{description}




\section{Device Output: The \texorpdfstring{{\tt DEVC}}{DEVC} Namelist Group}

Every device {\ct DEVC} contains a {\ct QUANTITY} that it monitors. Usually this {\ct QUANTITY} is written out to a comma-delimited spreadsheet file with the suffix {\ct \_devc.csv}. The quantities are listed in Table~\ref{tab:output}. Some quantities, such as {\ct MASS FLUX} and {\ct VOLUME FRACTION} and which are marked with an asterisk in Table~\ref{tab:output}, require a {\ct SPEC\_ID} to be specified also - refer to Section~\ref{info:outputquantities} for more details. There are two types of {\ct DEVC} output. The first is a time history of the given {\ct QUANTITY} over the course of the simulation. The second is a time-averaged profile consisting of a linear array of point devices. Each is explained below.

\subsection{Single Point Output}

If you just want to record the time history of the temperature at a given point, add the line:
\begin{lstlisting}
&DEVC XYZ=6.7,2.9,2.1, QUANTITY='TEMPERATURE', ID='T-1' /
\end{lstlisting}
and a column will be added to the output file {\ct CHID\_devc.csv} under the label {\ct 'T-1'}. In this case, the {\ct ID} has no other role than as a column label in the output file. FDS reports the value of the {\ct QUANTITY} in the cell where the point {\ct XYZ} is located.

\subsubsection{Devices on Solid Surfaces}

When prescribing a solid phase quantity, be sure to position the device at a solid surface. It is not always obvious where the solid surface is since the mesh does not always align with the input obstruction locations. To help locate the appropriate surface, the parameter {\ct IOR} {\em must} be included when designating a solid phase quantity, except when using one of the spatial statistics options that are described in Section~\ref{info:statistics} in which case the output quantity is not associated with just a single point on the surface. If the orientation of the solid surface is in the positive $x$ direction, set {\ct IOR=1}. If it is in the negative $x$ direction, set {\ct IOR=-1}, and so for the $y$ and $z$ directions. For example, the line
\begin{lstlisting}
&DEVC XYZ=0.7,0.9,2.1, QUANTITY='WALL TEMPERATURE', IOR=-2, ID='...' /
\end{lstlisting}
designates the surface temperature of a wall facing the negative $y$ direction. There are still instances where FDS cannot determine which solid surface is being designated, in which case an error message appears in the diagnostic output file. Re-position the device and try again. It is best to position the device, via the real triplet {\ct XYZ}, such that the device location is either at or within a cell width {\it outside} of the solid surface. The search algorithm in FDS will look for the nearest solid surface in the direction opposite to that indicated by {\ct IOR}.

\subsubsection{Integrated Quantities}

In addition to point measurements, the {\ct DEVC} group can be used to report integrated quantities (See Table~\ref{tab:output}). For example, you may want to know the mass flow out of a door or window. To report this, add the line
\begin{lstlisting}
&DEVC XB=0.3,0.5,2.1,2.5,3.0,3.0, QUANTITY='MASS FLOW', ID='whatever' /
\end{lstlisting}
Note that in this case, a plane is specified rather than a point. The sextuplet {\ct XB} is used for this purpose. Notice when a flow is desired, two of the six coordinates need to be the same. Another {\ct QUANTITY}, {\ct HRR}, can be used to compute the total heat release rate within a subset of the domain. In this case, the sextuplet {\ct XB} ought to define a volume rather than a plane. Specification of the plane or volume over which the integration is to take place can only be done using {\ct XB} -- avoid planes or volumes that cross multiple mesh boundaries. FDS has to decide which mesh to use in the integration, and it chooses the finest mesh overlapping the centroid of the designated plane or volume.



\subsection{Linear Array of Point Devices}
\label{info:line_file}

You can use a single {\ct DEVC} line to specify a linear array of devices. By adding the parameter {\ct POINTS} and using the sextuple coordinate array {\ct XB}, you can direct FDS to create a line of devices from $(x_1,y_1,z_1)$ to $(x_2,y_2,z_2)$. There are two options.

\subsubsection{Steady-State Profile}

Sometimes it is convenient to calculate a steady-state profile. For example, the vertical velocity profile along the centerline of a doorway can be recorded with the following line of input:
\begin{lstlisting}
&DEVC XB=X1,X2,Y1,Y2,Z1,Z2, QUANTITY='U-VELOCITY', ID='vel', POINTS=20,
      STATISTICS_START=20., STATISTICS_END=40. /
\end{lstlisting}
In a file called {\ct CHID\_line.csv}, there will be between 1 and 4 columns of data associated with this single {\ct DEVC} line. If {\ct X1} is different than {\ct X2}, there will be a column of $x$ coordinates associated with the linear array of points. The same holds for the $y$ and $z$ coordinates. The last column contains the 20 temperature points time-averaged over the interval between {\ct STATISTICS\_START} and {\ct STATISTICS\_END}. The default value of the latter is {\ct T\_END} and the former is half the total simulation time. This is a convenient way to output a time-averaged linear profile of a quantity, like an array of thermocouples.  Note that the statistics output to the {\ct \_line.csv} file start being averaged at {\ct T=STATISTICS\_START}.  Prior to this time, the values are zero.  This prevents initial transient from biasing the final average value or other temporal statistics.

A single ``line'' file can hold more than a single line of data. By default, the coordinate columns are labeled using the {\ct ID} of the {\ct DEVC} appended with either {\ct -x}, {\ct -y}, or {\ct -z}. To change these labels, use {\ct X\_ID}, {\ct Y\_ID}, and/or {\ct Z\_ID}. To suppress the coordinate columns altogether, add {\ct HIDE\_COORDINATES=.TRUE.} to the {\ct DEVC} line. This is convenient if you have multiple arrays of data that use the same coordinates. If you want the data plotted as a function of the distance from the origin, $r=\sqrt{x^2+y^2+z^2}$, provide the label {\ct R\_ID}. If you want the data plotted as a function of the distance from the first point on the line, ({\ct X1,Y1,Z1}), provide the label {\ct D\_ID}.

You can convert the spatial coordinate of a steady-state profile by setting {\ct COORD\_FACTOR} on the {\ct DEVC} line. For example, to convert from the default unit of meters to centimeters, set {\ct COORD\_FACTOR} to 100. Also set {\ct XYZ\_UNITS} to the appropriate character string, in this case {\ct XYZ\_UNITS='cm'}.

\subsubsection{Time-Varying Profile}

If you do not want a steady-state profile, but rather you just want to specify an array of evenly spaced devices, you can use a similar input line, except with the additional attribute {\ct TIME\_HISTORY}.
\begin{lstlisting}
&DEVC XB=X1,X2,Y1,Y2,Z1,Z2, QUANTITY='U-VELOCITY', ID='vel', POINTS=20,
      TIME_HISTORY=.TRUE. /
\end{lstlisting}
This directs FDS to just add 20 devices to the on-going list, saving you from having to write 20 {\ct DEVC} lines. The {\ct ID} for each device will be {\ct 'vel-01'}, {\ct 'vel-02'}, etc.



\subsubsection{Other Statistics for a Linear Array of Devices}

By default, when you specify multiple {\ct POINTS} on a {\ct DEVC} line and you do not specify {\ct TIME\_HISTORY=T}, a running average of the specified {\ct QUANTITY} is saved at each point location and written to the file with suffix {\ct \_line.csv} with the accumulated values at the time {\ct STATISTICS\_END}. However, you can apply any other {\ct TEMPORAL\_STATISTIC} and compute, for example, the root-mean-square ({\ct 'RMS'}), minimum ({\ct 'MIN'}), or maximum ({\ct 'MAX'}) value over the specified time interval.


\subsection{Quantities at Certain Depth}
\label{info:DEPTH}

To record the temperature inside the surface, you can use a device as follows:
\begin{lstlisting}
&DEVC XYZ=..., QUANTITY='INSIDE WALL TEMPERATURE', DEPTH=0.005, ID='Temp_1', IOR=3 /
\end{lstlisting}
The parameter {\ct DEPTH} (m) indicates the distance inside the solid surface. If {\ct DEPTH} is positive FDS outputs the temperature at the wall node given by moving {\ct DEPTH} from the front face of the surface. If negative, it is measured from the back surface (e.g. the location from the front given by the current solid surface thickness + {\ct DEPTH}). Note that if the wall thickness is decreasing over time due to the solid phase reactions, and the distance is measured from the current front surface, the measurement point will be moving towards the back side of the solid. Eventually, the measurement point may emerge from the solid, in which case it starts to show ambient temperature. Measuring the distance from the back surface can then be better suited for the purpose.

Note that {\ct DEPTH} may not perfectly align with the discrete spatial position of the cell center corresponding to the solid cell temperature being output by {\ct INSIDE WALL TEMPERATURE}.  Given the stretching and re-meshing done by the solid phase routines, it difficult to compute the local discrete cell position by hand.  If the discrete solid cell center position is needed, it may be output using
\begin{lstlisting}
&DEVC XYZ=..., QUANTITY='INSIDE WALL DEPTH', DEPTH=0.005, ID='XC_1', IOR=3 /
\end{lstlisting}
The output should lie within half a solid grid cell distance from the specified {\ct DEPTH}.

To record the material component's density with time, use the output quantity {\ct 'SOLID DENSITY'} in the following way:
\begin{lstlisting}
&DEVC ID='...', XYZ=..., IOR=3, QUANTITY='SOLID DENSITY', MATL_ID='wood', DEPTH=0.001 /
\end{lstlisting}
This produces a time history of the density of the material referred to as {\ct 'wood'} on a {\ct MATL} line. The density is recorded 1~mm beneath the surface which is oriented in the positive $z$ direction. Note that if {\ct 'wood'} is part of a mixture, the density represents the mass of {\ct 'wood'} per unit volume of the mixture.

To record the solid conductivity, use {\ct QUANTITY='SOLID CONDUCTIVITY'}. To record the solid specific heat, use {\ct QUANTITY='SOLID SPECIFIC HEAT'}. These quantities do not need the {\ct MATL\_ID} keyword.

Note that these quantities are allowed only as a {\ct DEVC}, not a {\ct BNDF}, output.


\subsection{Back Surface Temperature}
\label{info:BACK}

If you just want to know the temperature of the back surface of the ``wall,'' then use
\begin{lstlisting}
&DEVC XYZ=..., QUANTITY='BACK WALL TEMPERATURE', ID='Temp_b', IOR=3 /
\end{lstlisting}
Note that this quantity is only meaningful if the front or exposed surface of the ``wall'' has the attribute {\ct BACKING='EXPOSED'} on the {\ct SURF} line that defines it. The coordinates, {\ct XYZ}, and orientation, {\ct IOR}, refer to the front surface. To check that the heat conduction calculation is being done properly, you can add the additional line
\begin{lstlisting}
&DEVC XYZ=..., QUANTITY='WALL TEMPERATURE', ID='Temp_f', IOR=-3 /
\end{lstlisting}
where now {\ct XYZ} and {\ct IOR} refer to the coordinates and orientation of the back side of the wall. These two wall temperatures ought to be the same. Remember that the ``wall'' in this case can only be at most one mesh cell thick, and its {\ct THICKNESS} need not be the same as the mesh cell width. Rather, the {\ct THICKNESS} ought to be the actual thickness of the ``wall'' through which FDS performs a 1-D heat conduction calculation.


\section{In-Depth Profiles within Solids: The \texorpdfstring{{\tt PROF}}{PROF} Namelist Group}
\label{info:PROF}

FDS uses a fine one-dimensional grid at each boundary cell to calculate the heat conduction and reactions within a solid. The solid can be a wall cell or a Lagrangian particle. In either case, use the {\ct PROF} output to record the properties of the solid in depth at discrete intervals of time.

The parameters for a {\ct PROF} line are listed in Table~\ref{tbl:PROF}. For a wall cell, the parameters are similar to those used to specify a surface quantity in the {\ct DEVC} group. {\ct XYZ} designates the triplet of coordinates, {\ct IOR} the orientation, and {\ct ID} an identifying character string. Here is an example of how you would use this feature to get a time history of temperature profiles within a wall cell:
\begin{lstlisting}
&PROF ID='T-1', XYZ=..., QUANTITY='TEMPERATURE', IOR=3 /
\end{lstlisting}
For a particle, you must reference an {\ct INIT} line used to place the particle within the domain:
\begin{lstlisting}
&INIT ID='my particle', XYZ=..., N_PARTICLES=1, PART_ID='...' /
&PROF ID='T-2', INIT_ID='my particle', QUANTITY='TEMPERATURE' /
\end{lstlisting}
For a particle, do not specify {\ct XYZ} or {\ct IOR} on the {\ct PROF} line.

The {\ct QUANTITY} is the physical quantity to monitor. Other possible quantities are the total {\ct 'DENSITY'} or the density of a particular solid material component, {\ct '[MATL\_ID]'}, where {\ct [MATL\_ID]} is the name of the material component. Each {\ct PROF} line creates a separate file. The first number in each row is the time at which the profile is extracted. The second number is the number of ``nodes,'' $n$, which is the number of solid phase cells plus 1. The next $n$ numbers are the node coordinates, running from 0 at the surface to the full {\ct THICKNESS} at the end. The next $n$ numbers are the values of the {\ct QUANTITY} at the node points. The first of these values is located at the surface.

There is a second optional format. If you specify {\ct FORMAT\_INDEX=2} on the {\ct PROF} line, the resulting file will contain columns containing only the final set of node coordinates and quantity values. This is handy for displaying a steady-state profile.



\section{Animated Planar Slices: The \texorpdfstring{{\tt SLCF}}{SLCF} Namelist Group}
\label{info:SLCF}

The {\ct SLCF} (``slice file'') namelist group parameters (Table~\ref{tbl:SLCF}) allows you to record various gas phase quantities at more than a single point. A ``slice'' refers to a subset of the whole domain. It can be a line, plane, or volume, depending on the values of {\ct XB}. The sextuplet {\ct XB} indicates the boundaries of the ``slice'' plane. {\ct XB} is prescribed as in the {\ct OBST} or {\ct VENT} groups, with the possibility that 0, 2, or 4 out of the 6 values be the same to indicate a volume, plane or line, respectively. A handy trick is to specify, for example, {\ct PBY=5.3} instead of {\ct XB} if it is desired that the entire plane $y=5.3$ slicing through the domain be saved. {\ct PBX} and {\ct PBZ} control planes perpendicular to the $x$ and $z$ axes, respectively.

By default, 1-D and 2-D slice files are saved {\ct NFRAMES} times per simulation. You can control the frequency of output with {\ct DT\_SLCF} on the {\ct DUMP} line. If the ``slice'' is a 3-D volume, then its output frequency is controlled by the parameter {\ct DT\_SL3D}.  By default, FDS sets {\ct DT\_SL3D=(T\_END-T\_BEGIN)/5}.  You may specify a different value of {\ct DT\_SL3D} on {\ct DUMP}.  Note that 3-D slice files can become extremely large if {\ct DT\_SL3D} is small.

Animated vectors can be created in Smokeview if a given {\ct SLCF} line has the attribute {\ct VECTOR=.TRUE.} If two {\ct SLCF} entries are in the same plane, then only one of the lines needs to have {\ct VECTOR=.TRUE.} Otherwise, a redundant set of velocity component slices will be created.

Normally, FDS averages slice file data at cell corners. For example, gas temperatures are computed at cell centers, but they are linearly interpolated to cell corners and output to a file that is read by Smokeview. To prevent this from happening, set {\ct CELL\_CENTERED=.TRUE.} This forces FDS to output the actual cell-centered data with no averaging. Note that this feature is mainly useful for diagnostics because it enables you to visualize the values that FDS actually computes.  If {\ct CELL\_CENTERED=.TRUE.} is combined with {\ct VECTOR=.TRUE.} then the staggered velocity components will be displayed.  For example,
\begin{lstlisting}
&SLCF PBY=0, QUANTITY='VELOCITY', VECTOR=.TRUE., CELL_CENTERED=.TRUE. /
\end{lstlisting}
will show the staggered velocity components as cell face normal vectors in Smokeview.

Slice file information is recorded in files (See Section~\ref{out:SLCF}) labeled {\ct CHID\_$n$.sf}, where $n$ is the index of the slice file. A short Fortran program {\ct fds2ascii.f90} produces a text file from a line, plane or volume of data. See Section~\ref{info:fds2ascii} for more details.

By default, Smokeview will blank slice file data inside obstructions.  However, this is expensive to load at startup in Smokeview for large cases.  If you wish Smokeview not to store this blanking array, set {\ct IBLANK\_SMV=.FALSE.} on {\ct MISC}.  Another option is to run Smokeview from the command line and to add {\ct -noblank} as an option.


\section{Animated Boundary Quantities: The \texorpdfstring{{\tt BNDF}}{BNDF} Namelist Group}
\label{info:BNDF}

The {\ct BNDF} (``boundary file'') namelist group parameters allows you to record surface quantities at all solid obstructions. As with the {\ct SLCF} group, each quantity is prescribed with a separate {\ct BNDF} line, and the output files are of the form {\ct CHID\_$n$.bf}. No physical coordinates need be specified, however, just {\ct QUANTITY}. See Table \ref{tab:output}. For certain output quantities, additional parameters need to be specified via the {\ct PROP} namelist group. In such cases, add the character string, {\ct PROP\_ID}, to the {\ct BNDF} line to tell FDS where to find the necessary extra information.

Note that {\ct BNDF} files (Section~\ref{out:BNDF}) can become very large, so be careful in prescribing the time interval, {\ct DT\_BNDF} on the {\ct DUMP} line. One way to reduce the size of the output file is to turn off the drawing of boundary information on desired obstructions. On any given {\ct OBST} line, if the string {\ct BNDF\_OBST=.FALSE.} is included, the obstruction is not colored. To turn off all boundary drawing, set {\ct BNDF\_DEFAULT=.FALSE.} on the {\ct MISC} line. Then individual obstructions can be turned back on with {\ct BNDF\_OBST=.TRUE.} on the appropriate {\ct OBST} line. Individual faces of a given obstruction can be controlled via {\ct BNDF\_FACE(IOR)}, where {\ct IOR} is the index of orientation (+1 for the positive $x$ direction, -1 for negative, and so on). Normally, FDS averages boundary file data at cell corners. For example, surface temperatures are computed at the center of each surface cell, but they are linearly interpolated to cell corners and output to a file that is read by Smokeview. To prevent this from happening, set {\ct CELL\_CENTERED=.TRUE.} on the {\ct BNDF} line. This forces FDS to output the actual cell-centered data with no averaging. Note that this feature is mainly useful for diagnostics.

Sometimes it is useful to render the {\ct QUANTITY} integrated over time. For example, a heat flux in units of kW/m$^2$ can be integrated in time producing the total energy absorbed by the surface in units of kJ/m$^2$. To do this, set {\ct TEMPORAL\_STATISTIC} equal to {\ct 'TIME INTEGRAL'} on the {\ct BNDF} line. Note that there are no other options for {\ct TEMPORAL\_STATISTIC} on a {\ct BNDF} line.



\section{Animated Isosurfaces: The \texorpdfstring{{\tt ISOF}}{ISOF} Namelist Group}
\label{info:ISOF}

The {\ct ISOF} (``ISOsurface File'') namelist group creates three-dimensional animated contours of gas phase scalar quantities. For example, a 300~$^\circ$C temperature isosurface is a 3-D surface on which the gas temperature is 300~$^\circ$C. Three different values of the temperature can be saved via the line:
\begin{lstlisting}
&ISOF QUANTITY='TEMPERATURE', VALUE(1)=50., VALUE(2)=200., VALUE(3)=500. /
\end{lstlisting}
where the values are in $^\circ$C. Note that the isosurface output files {\ct CHID\_$n$.iso} can become very large, so experiment with different sampling rates ({\ct DT\_ISOF} on the {\ct DUMP} line).
The parameter {\ct QUANTITY2}\ can be used to color the isosurface.
For example, the line:
\begin{lstlisting}
&ISOF QUANTITY='MIXTURE FRACTION' , VALUE(1)=0.05, QUANTITY2='TEMPERATURE' /
\end{lstlisting}
draws a surface where the mixture fraction has a value of 0.05~kg/kg and colors the surface this using temperature.
The parameter {\ct SKIP=n}\ (default: 1) can also be used to reduce data by skipping {\ct n-1}\ values in each direction.
The parameter {\ct DELTA=val}\ can also be used to reduce data by forcing each triangle to have all
sides larger than {\ct val}.

Any gas phase quantity can be animated via iso-surfaces, but use caution. To render an iso-surface, the desired quantity must be computed in every mesh cell at every output time step. For quantities like {\ct 'TEMPERATURE'}, this is not a problem, as FDS computes it and saves it anyway. However, species volume fractions demand substantial amounts of time to compute at each mesh cell. Remember to include the {\ct SPEC\_ID} corresponding to the given {\ct QUANTITY} if necessary.




\section{Plot3D Static Data Dumps}
\label{info:PL3D}

Data stored in Plot3D~\cite{PLOT3D} files use a format developed by NASA that is used by many CFD programs for representing simulation results. See Section~\ref{out:PL3D} for a description of the file structure. Plot3D data is visualized in three ways: as 2-D contours, vector plots and iso-surfaces. Vector plots may be viewed if one or more of the $u$, $v$ and $w$ velocity components are stored in the Plot3D file. The vector length and direction show the direction and relative speed of the fluid flow. The vector colors show a scalar fluid quantity such as temperature. Five quantities are written out to a file at one instant in time. The default specification is:
\begin{lstlisting}
&DUMP ..., PLOT3D_QUANTITY(1:5)='TEMPERATURE',
      'U-VELOCITY','V-VELOCITY','W-VELOCITY','HRRPUV' /
\end{lstlisting}
It's best to leave the velocity components as is, because Smokeview uses them to draw velocity vectors. If any of the specified quantities require the additional specification of a particular species, use {\ct PLOT3D\_SPEC\_ID(n)} to provide the {\ct SPEC\_ID} for {\ct PLOT3D\_QUANTITY(n)}.

Plot3D data are stored in files with extension {\ct .q} . There is an optional file that can be output with coordinate information if another visualization package is being used to render the files. If you write {\ct WRITE\_XYZ=.TRUE.} on the {\ct DUMP} line, a file with suffix {\ct .xyz} is written out. Smokeview does not require this file because the coordinate information can be obtained elsewhere.

Past versions of FDS (1-5) output Plot3D files by default. Now, you must specify the time interval between dumps using {\ct DT\_PL3D} on the {\ct DUMP} line.



\section{SMOKE3D: Realistic Smoke and Fire}
\label{info:SMOKE3D}

When you do a fire simulation, FDS automatically creates two output files that are rendered by Smokeview as realistic looking smoke and fire. By default, the output quantities are the {\ct 'DENSITY'} of {\ct 'SOOT'} and {\ct 'HRRPUV'} (Heat Release Rate Per Unit Volume). You have the option of rendering any other species besides {\ct 'SOOT'}, so long as the {\ct MASS\_EXTINCTION\_COEFFICIENT} on the {\ct SPEC} line is appropriate in describing the attenuation of visible light by the specified gas species. Here is an example of how to change the smoke species. Normally, you do not need to do this as the ``smoke'' is an assumed part of the default combustion model when a non-zero {\ct SOOT\_YIELD} is defined on the {\ct REAC} line.
\begin{lstlisting}
&SPEC ID='MY SMOKE', MW=29., MASS_EXTINCTION_COEFFICIENT=8700. /
&DUMP SMOKE3D_SPEC_ID='MY SMOKE' /
\end{lstlisting}
The {\ct MASS\_EXTINCTION\_COEFFICIENT} is passed to Smokeview to be used for visualization.



\section{Particle Output Quantities}
\label{info:part_output}

This section discusses output options for Lagrangian particles.

\subsection{Liquid Droplets that are Attached to Solid Surfaces}
\label{bucket_test_1}

Liquid droplets (as opposed to solid particles) ``stick'' to solid surfaces unless directed otherwise. There are various quantities that describe these populations. For example, {\ct 'MPUA'} is the \underline{M}ass \underline{P}er \underline{U}nit \underline{A}rea of the droplets defined by {\ct PART\_ID}. Likewise, {\ct 'AMPUA'} is the \underline{A}ccumulated \underline{M}ass \underline{P}er \underline{U}nit \underline{A}rea. Both of these are given in units of kg/m$^2$. Think of these outputs as measures of the instantaneous mass density per unit area, and the accumulated total, respectively. These quantities are not identical measures.  The quantity {\ct 'AMPUA'} is analogous to a ``bucket test,'' where the droplets are collected in buckets and the total mass determined at the end of a given time period. In this case each grid cell on the floor is considered its own bucket.  Each droplet is counted only once when it reaches the floor\footnote{Be aware of the fact that the default behavior for liquid droplets hitting the ``floor,'' that is, the plane $z=\hbox{\ct ZMIN}$, is to disappear ({\ct POROUS\_FLOOR=.TRUE.} on the {\ct MISC} line). In this case, {\ct 'MPUA'} will be zero, but {\ct 'AMPUA'} will not. FDS stores the droplet mass just before removing the droplet from the simulation for the purpose of saving CPU time.}. {\ct MPUA} counts a droplet whenever it is on any solid surface, including the walls. If the droplet moves from one solid wall cell to another, it will be counted again. The cooling of a solid surface by droplets of a given type is given by {\ct 'CPUA'}, the \underline{C}ooling \underline{P}er \underline{U}nit \underline{A}rea in units of kW/m$^2$. Since a typical sprinkler simulation only tracks a small fraction of the droplets emitted from a sprinkler, both {\ct MPUA} and {\ct CPUA} also perform an exponential smoothing. This avoids having spotted distributions on surfaces due to the infrequent arrival of droplets that likely have a high weighting factor.

Each of the output quantities mentioned above has a variant in which the quantity is summed by species rather than particle type. For example, the quantity {\ct 'AMPUA\_Z'} along with a specified {\ct SPEC\_ID} rather than a {\ct PART\_ID} will sum the given output quantity over all particle classes with the given {\ct SPEC\_ID}.

As an example of how to use these kinds of output quantities, the test case {\ct bucket\_test\_1} describes a single sprinkler mounted 10~cm below a 5~m ceiling. Water flows for 30~s at a constant rate of 180~L/min (ramped up and down in 1~s).  The simulation continues for another 10~s to allow water drops time to reach the floor. The total mass of water discharged is
\be
  \mathrm{ 180 \; \frac{L}{min} \times 1 \; \frac{kg}{L} \times \frac{1}{60} \; \frac{min}{s} \times 30 \; s = 90 \; kg }
\ee
In the simulation, the quantity {\ct 'AMPUA'} with {\ct SPATIAL\_STATISTIC='SURFACE INTEGRAL'} is specified on the {\ct DEVC} line.  This results in FDS summing {\ct 'AMPUA'} over each grid cell in the volume defined by {\ct XB}, in this case the entire floor, analogous to if there were an single bucket present that was the same size as the area specified with {\ct XB}. Summing the values of {\ct 'AMPUA'} over the entire floor yields a total of 90~kg (Fig.~\ref{bucket_test_fig}). Note that there really is no need to time-average the results. The quantity is inherently accumulating.

\begin{figure}[ht]
\centering
\includegraphics[width=3in]{SCRIPT_FIGURES/bucket_test_1}
\caption[Results of the {\ct bucket\_test\_1} case]{Accumulated water collected at the floor in the {\ct bucket\_test\_1} case.}
\label{bucket_test_fig}
\end{figure}


\subsection{Solid Particles on Solid Surfaces}

If you want to monitor the accumulation of solid particles that have fallen on a solid surface, use a device as follows:
\begin{lstlisting}
&DEVC ID=..., XB=..., QUANTITY='MPUV', PART_ID='rods', SPATIAL_STATISTIC='VOLUME INTEGRAL' /
\end{lstlisting}
The volume over which to integrate, {\ct XB}, should be at least one grid cell thick above the surface.


\subsection{Droplet and Particle Densities and Fluxes in the Gas Phase}
\label{bucket_test_4}

Away from solid surfaces, {\ct 'MPUV'} is the \underline{M}ass \underline{P}er \underline{U}nit \underline{V}olume of particles or droplets of type ({\ct PART\_ID}) in units of kg/m$^3$.  {\ct 'MPUV\_Z'} provides the same information integrated over all droplets of a single species, ({\ct SPEC\_ID}).

The quantities {\ct 'PARTICLE FLUX X'},  {\ct 'PARTICLE FLUX Y'}, and {\ct 'PARTICLE FLUX Z'} produce slice and Plot3D colored contours of the mass flux of particles in the $x$, $y$, and $z$ directions, respectively, in units of kg/m$^2$/s. You can also apply these quantities to a device. For example, in the case called {\ct bucket\_test\_4.fds}, the input line
\begin{lstlisting}
&DEVC XB=..., ID='flux', QUANTITY='PARTICLE FLUX Z', SPATIAL_STATISTIC='AREA INTEGRAL'  /
\end{lstlisting}
records the integrated mass flux of {\em all} particles passing through the given horizontal plane. Figure~\ref{bucket_test_4_fig} presents the results of this simple test case in which water spraying at a rate of 0.0005~kg/s for 55~s passes through a measurement plane and onto the floor. The total water accumulated is 0.0275~kg.

\begin{figure}[ht]
\includegraphics[width=3in]{SCRIPT_FIGURES/bucket_test_4b}
\includegraphics[width=3in]{SCRIPT_FIGURES/bucket_test_4}
\caption[Results of the {\ct bucket\_test\_4} case]{Mass flux and accumulated water collected at the floor in the {\ct bucket\_test\_4} case.}
\label{bucket_test_4_fig}
\end{figure}


\subsection{Coloring Particles and Droplets in Smokeview}

The parameter {\ct QUANTITIES} on the {\ct PART} line is an array of character strings indicating which scalar quantities should be used to color particles and droplets in Smokeview. The choices are \\
{\ct 'PARTICLE TEMPERATURE'} ($^\circ$C) \\
{\ct 'PARTICLE DIAMETER'} ($\mu$m) \\
{\ct 'PARTICLE VELOCITY'} (m/s) \\
{\ct 'PARTICLE MASS'} (kg) \\
{\ct 'PARTICLE AGE'} (s) \\
{\ct 'PARTICLE WEIGHTING FACTOR'} \\
{\ct 'PARTICLE PHASE'} \\
{\ct 'PARTICLE X'}, {\ct 'PARTICLE Y'}, {\ct 'PARTICLE Z'} (m) \\
{\ct 'PARTICLE U'}, {\ct 'PARTICLE V'}, {\ct 'PARTICLE W'} (m/s) \\
By default, if no {\ct QUANTITIES} are specified and none are selected in Smokeview, then Smokeview will display particles with a single color. To select this color specify either {\ct RGB} or {\ct COLOR}. By default, water droplets are colored blue. All others are colored black.

The {\ct PARTICLE WEIGHTING FACTOR} describes how many actual particles each of the computational particles represent.

For solid particles with a specified {\ct SURF\_ID}, you may specify any of the solid phase output quantities listed in Table~\ref{tab:output}. If the specified quantity is associated with a species, use the parameter \linebreak[4] {\ct QUANTITIES\_SPEC\_ID(N)} to specify the species. Here {\ct N} refers to the order of the specified output quantities on the {\ct PART} line.


\subsection{Detailed Properties of Solid Particles}

You may output properties of a single solid particle using a {\ct DEVC} (device) line. For example, the lines:
\begin{lstlisting}
&INIT ID='my particle', PART_ID='...', XB=..., N_PARTICLES=1 /
&DEVC ID='...', INIT_ID='my particle', QUANTITY='WALL TEMPERATURE' /
\end{lstlisting}
output the surface temperature of a single particle that has been introduced into the simulation via an {\ct INIT} line.

If the particle is split (by means of multiple {\ct ORIENTATION} vectors on the {\ct PART} line), you can specify which of the particle fragments you want using the parameter {\ct ORIENTATION\_NUMBER} on the {\ct DEVC} line.

If the {\ct INIT} line has a {\ct MULT\_ID}; that is, an array of particles is introduced via this single {\ct INIT} line, then the {\ct INIT\_ID} for each takes the form {\ct '[ID]-00308'}, where {\ct ID} is that of the {\ct INIT} line, and 308 refers to the 308-th {\ct INIT} line generated by the multiplicative sequence. The {\ct INIT} lines are generated by looping over the $x$ indices, then $y$, then $z$. For example, the following input lines
\begin{lstlisting}
&INIT ID='P', PART_ID='CRIB1', XYZ=0.005,0.005,0.005 ,
      N_PARTICLES=1, CELL_CENTERED=.TRUE., MULT_ID='array' /
&MULT ID='array', DX=0.01, DY=0.01, DZ=0.01, I_LOWER=0, I_UPPER=9,
      J_LOWER=0, J_UPPER=9, K_LOWER=0, K_UPPER=3 /
&DEVC ID='T307', INIT_ID='P-00307', QUANTITY='WALL TEMPERATURE' /
\end{lstlisting}
specify an array of 10 by 10 by 4 particles. We want to record the surface temperature of the 307-th particle. See Section~\ref{info:MULT} for details of how the {\ct MULT} line is interpreted.

Solid particles can be used as a surrogate targets. For example, the following lines of input create a massless particle that can be used to record a heat flux at a given location away from a solid wall. In this case, the mock heat flux gauge is pointing in the $-x$ direction:
\begin{lstlisting}
&DEVC ID='flux', INIT_ID='f1', QUANTITY='RADIATIVE HEAT FLUX' /
&INIT ID='f1', XYZ=..., N_PARTICLES=1, PART_ID='rad gauge' /
&PART ID='rad gauge', STATIC=.TRUE., ORIENTATION=-1,0,0, SURF_ID='target' /
&SURF ID='target', RADIUS=0.001, GEOMETRY='SPHERICAL', EMISSIVITY=1. /
\end{lstlisting}
Note that the {\ct DEVC} line does not contain device coordinates, but rather a reference to the {\ct INIT} line that positions the single surrogate particle at the point {\ct XYZ}. The {\ct INIT} line references the {\ct PART} line, which provides information about the particle, in particular the orientation of the heat flux gauge. The reference to the {\ct SURF} line is mainly for consistency -- FDS needs to know something about the particle's geometry even though it is really just a ``target.''  Its volume is meaningless. The functionality of surrogate particles can be extended to model an array of devices. Instead of one heat flux gauge, we can create a line of them:
\begin{lstlisting}
&DEVC ID='flux', INIT_ID='f1', POINTS=34, QUANTITY='RADIATIVE HEAT FLUX', X_ID='x' /
&INIT ID='f1', XYZ=..., N_PARTICLES=34, DX=0.05, PART_ID='rad gauge' /
\end{lstlisting}
Note that the parameter {\ct DX} on the {\ct INIT} line creates a line of particles starting at the point {\ct XYZ} and repeating every 0.05~m. For more information about specifying arrays of devices via the parameter {\ct POINTS}, see Section~\ref{info:line_file}.





\section{Special Output Quantities}

This section lists a variety of output quantities that are useful for studying thermally-driven flows, combustion, pyrolysis, and so forth. Note that some of the output quantities can be produced in a variety of ways.


\subsection{Heat Release Rate}
\label{info:HRR}
\label{hallways}

Quantities associated with the overall energy budget are reported in the comma delimited file {\ct CHID\_hrr.csv}.  This file is automatically generated; the only input parameter associated with it is {\ct DT\_HRR} on the {\ct DUMP} line. The columns in this file record the time history of the integrals of the terms in the enthalpy transport equation. The columns are defined as follows:
\begin{eqnarray}
\label{eqn_enthalpytransport}
\underbrace{\frac{\partial}{\partial t} \int \rho h_s \, \d V }_{\hbox{\ct Q\_ENTH}} &=&
\underbrace{\dm_b h_{s,b} - \int \rho \bu h_{\rm s} \cdot \d {\bf S}}_{\hbox{\ct Q\_CONV}}
\; + \; \underbrace{\dq_{b,w} + \int k \nabla T \cdot \d {\bf S}}_{\hbox{\ct Q\_COND}}
\; + \; \underbrace{\sum_\alpha \int h_{s,\alpha} \, \rho D_\alpha \nabla Y_\alpha \cdot \d {\bf S}}_{\hbox{\ct Q\_DIFF}}  \nonumber \\
&&
+\underbrace{\dq_{b,r} - \int \dot{\mathbf{q}}^{\prime\prime}_{r} \cdot \d {\bf S}}_{\hbox{\ct Q\_RADI}}
\; + \; \underbrace{\int \dot{q}''' \, \d V}_{\hbox{\ct HRR}}
\; + \; \underbrace{\int \frac{d \overline{p} }{\d t} \, \d V}_{\hbox{\ct Q\_PRES}}
\; + \; \underbrace{\left( -\dq_{b,c} - \dq_{b,r} - \dq_{b,w} \right) }_{\hbox{\ct Q\_PART}}
\end{eqnarray}
An additional column, {\ct Q\_TOTAL}, includes the sum of the terms on the right hand side of the equation. Ideally, this sum should equal the term on the left, {\ct Q\_ENTH}. All terms are reported in units of kW. Note that the terms that make up {\ct Q\_PART} are summed over the Lagrangian particles. They represent the heat absorbed by the particles via \underline{c}onvection, \underline{r}adiation, and conduction from the \underline{w}all.

The other columns in the file contain the total burning rate of fuel, in units of kg/s, and the zone pressures. Note that the reported value of the burning rate is not adjusted to account for the possibility that each individual
material might have a different heat of combustion. For this reason, it is not always the case that the reported total burning rate multiplied by the gas phase heat of combustion is equal to the reported heat release rate.

Note that the volume integrations in Eq.~(\ref{eqn_enthalpytransport}) are performed over the entire domain. The differential, $\d V$, is the product of the local grid cell dimensions, $\d x \, \d y \, \d z$. For the special case of two-dimensional cylindrical coordinates, $\d V=r \, \d r \, \d \theta \, \d z$, where $r=x$, $\d r = \d x$, and $\d \theta = \d y$.

As a test of the energy balance, a sample case called {\ct Pressure\_Solver/hallways.fds} simulates a fire near the end of five connected hallways. The other end of the hallways is open. As is seen in Fig.~\ref{hallways_energy}, the quantities {\ct Q\_ENTH} and {\ct Q\_TOTAL} are very closely matched, indicating that the sources of energy loss and gain are properly added and subtracted from the energy equation. As expected, the net energy gain/loss eventually goes to zero as the compartment reaches a quasi-steady state.
\begin{figure}[ht]
\centering
\includegraphics[width=3in]{SCRIPT_FIGURES/hallways}
\caption[Results of the {\ct hallways} test case]{The energy budget for the {\ct hallways} test case.}
\label{hallways_energy}
\end{figure}


\subsection{Mass Loss Rates}

The rate at which gas species are generated at solid surfaces, solid particles, or liquid droplets is recorded in the file {\ct CHID\_hrr.csv}. This file is automatically generated; the only input parameter associated with it is {\ct DT\_HRR} on the {\ct DUMP} line. This file contains quantities related to the energy budget (Section~\ref{info:HRR}), and the pressures of user-designated pressure zones (Section~\ref{info:pressurezone}). The generation rate of fuel gas (often called the burning rate) is given in the column entitled {\ct MLR\_FUEL} in units of kg/s. The generation rate of all gas species, including fuel, is given in the column entitled {\ct MLR\_TOTAL} in units of kg/s.


\subsection{Zone Pressures}
\label{info:pressurezone}

If you specify pressure {\ct ZONE}s; that is, specific areas of the domain where the background pressure rises above ambient, the pressure of each zone is listed in the file {\ct CHID\_hrr.csv}.


\subsection{Visibility and Obscuration}
\label{info:visibility}
\label{info:obscuration}

If you are performing a fire calculation using the simple chemistry approach, the smoke is tracked along with all other major products of combustion. The most useful quantity for assessing visibility in a space is the {\em light extinction coefficient}, $K$~\cite{SFPE:Mulholland}. The intensity of monochromatic light passing a distance $L$ through smoke is attenuated according to
\be I/I_0 = {\rm e}^{-KL} \ee
The light extinction coefficient, $K$, is a product of a mass specific extinction coefficient, $K_{\rm m}$, which is fuel dependent, and the density of smoke particulate, $\rho Y_{\rm S}$
\be K = K_{\rm m} \; \rho \, Y_{\rm S} \label{mec} \ee
Devices that output a \% obscuration such as a {\ct DEVC} with a {\ct QUANTITY} of {\ct 'ASPIRATION'}, {\ct 'CHAMBER OBSCURATION'} (smoke detector), or {\ct 'PATH OBSCURATION'} (beam detector) are discussed respectively in Section~\ref{info:aspiration_detector}, Section~\ref{info:smoke_detector}, and Section~\ref{info:beam_detector}.

Estimates of visibility through smoke can be made by using the equation
\be  S = C/K  \label{vis}  \ee
where $C$ is a non-dimensional constant characteristic of the type of object being viewed through the smoke, i.e., $C=8$ for a light-emitting sign and $C=3$ for a light-reflecting sign~\cite{SFPE:Mulholland}. Since $K$ varies from point to point in the domain, the visibility $S$ does as well.

Three parameters control smoke production and visibility. The first is the {\ct SOOT\_YIELD} on the {\ct REAC} line, defined as the fraction of fuel mass that is converted to soot if the simple chemistry approach is being used. The second parameter, {\ct MASS\_EXTINCTION\_COEFFICIENT}, is the $K_{\rm m}$ in Eq.~(\ref{mec}). It is defined on one or more of the {\ct SPEC} lines\footnote{When using the simple chemistry combustion model, you can change the default mass extinction coefficient by adding a line to the input file of the form: \tt{\footnotesize \&SPEC ID='SOOT', MASS\_EXTINCTION\_COEFFICIENT=..., LUMPED\_COMPONENT\_ONLY=.TRUE. /} } for the various light absorbing gas species. Its default value is 8700~m$^2$/kg, a value suggested for flaming combustion of wood and plastics\footnote{For most flaming fuels, a suggested value for $K_{\rm m}$ is 8700~m$^2$/kg~$\pm$~1100~m$^2$/kg at a wavelength of 633~nm~\cite{Mulholland:F+M}}. The third parameter, {\ct VISIBILITY\_FACTOR} on the {\ct MISC} line, is the constant $C$ in Eq.~(\ref{vis}). It is 3 by default.

The gas phase output quantity {\ct 'EXTINCTION COEFFICIENT'} is $K$. A similar quantity is the {\ct 'OPTICAL DENSITY'}, $D=K/2.3$, the result of using $\log_{10}$ in the definition \be D \equiv - \frac{1}{L} \, \log_{10} \left( \frac{I}{I_0} \right) = K \, \log_{10} {\rm e}   \ee The visibility $S$ is output via the {\ct QUANTITY} called {\ct 'VISIBILITY'}. Note that, by default, the visibility is associated with the smoke that is implicitly defined by the simple chemistry model. However, this quantity can also be associated with an explicitly defined species via the inclusion of a {\ct SPEC\_ID}. In other words, you can specify the output quantity {\ct 'VISIBILITY'} along with a {\ct SPEC\_ID}. This does not require that you do a simple chemistry calculation; only that you have specified the given species via a separate {\ct SPEC} line. You can specify a unique {\ct MASS\_EXTINCTION\_COEFFICIENT} on the {\ct SPEC} line as well.

Note that FDS cannot report a visibility of infinity, but rather reports a {\ct MAXIMUM\_VISIBILITY} that you can control via the {\ct MISC} line. The default is 30~m.


\subsection{Layer Height and the Average Upper and Lower Layer Temperatures}
\label{info:layerheight}

Fire protection engineers often need to estimate the location of the interface between the hot, smoke-laden upper layer and the cooler lower layer in a burning compartment.  Relatively simple fire models, often referred to as {\em two-zone models}, compute this quantity directly, along with the average temperature of the upper and lower layers.  In a computational fluid dynamics (CFD) model like FDS, there are not two distinct zones, but rather a continuous profile of temperature. Nevertheless, there are methods that have been developed to estimate layer height and average temperatures from a continuous vertical profile of temperature. One such method~\cite{Janssens:JFS1992} is as follows: Consider a continuous function $T(z)$ defining temperature $T$ as a function of height above the floor $z$, where $z=0$ is the floor and $z=H$ is the ceiling. Define $T_{\rm u}$ as the upper layer temperature, $T_{\rm l}$ as the lower layer temperature, and $z_{\rm int}$ as the interface height. Compute the quantities:
\begin{eqnarray*} (H-z_{\rm int})\; T_{\rm u} + z_{\rm int} \; T_{\rm l} = \int_0^H \; T(z) \; \d z &=& I_1 \\ [0.1in]
                  (H-z_{\rm int})\; \frac{1}{T_{\rm u}} + z_{\rm int} \; \frac{1}{T_{\rm l}} = \int_0^H \; \frac{1}{T(z)} \; \d z &=& I_2
\end{eqnarray*}
Solve for $z_{\rm int}$:
\be
   z_{\rm int} = \frac{ T_{\rm l} \, (I_1 \, I_2 - H^2)}{I_1+I_2 \, T_{\rm l}^2 - 2\, T_{\rm l} \, H}
\ee
Let $T_{\rm l}$ be the temperature in the lowest mesh cell and, using Simpson's Rule, perform the numerical integration of $I_1$ and $I_2$. $T_{\rm u}$ is defined as the average upper layer temperature via
\be
   (H-z_{\rm int})\; T_{\rm u} = \int_{z_{\rm int}}^H \; T(z) \; \d z
\ee
Further discussion of similar procedures can be found in Ref.~\cite{He:1}.

The quantities {\ct 'LAYER HEIGHT'}, {\ct 'UPPER TEMPERATURE'} and {\ct 'LOWER TEMPERATURE'} can be designated via {\ct DEVC} lines in the input file. For example, the line:
\begin{lstlisting}
&DEVC XB=2.0,2.0,3.0,3.0,0.0,3.0, QUANTITY='LAYER HEIGHT', ID='whatever' /
\end{lstlisting}
produces a time history of the smoke layer height at $x=2$ and $y=3$ between $z=0$ and $z=3$. If multiple meshes are being used, the vertical path {\em cannot} cross mesh boundaries.



\subsection{Thermocouples}
\label{info:THERMOCOUPLE}

The output quantity {\ct THERMOCOUPLE} is the temperature of a modeled thermocouple. The thermocouple temperature lags the true gas temperature by an amount determined mainly by its bead size. It is found by solving the following equation for the thermocouple temperature, $T_{\rm TC}$~\cite{Welsh:1}
\be
   \rho_{\rm TC} \, c_{\rm TC} \, \frac{\d T_{\rm TC}}{\d t} = \epsilon_{\rm TC} \, (U/4 - \sigma T_{\rm TC}^4) + h(T_{\rm g} - T_{\rm TC}) = 0
   \label{TC}
\ee
where $\epsilon_{\rm TC}$ is the emissivity of the thermocouple, $U$ is the integrated radiative intensity, $T_{\rm g}$ is the true gas temperature, and $h$ is the heat transfer coefficient to a small sphere, $h=k \, \NU / D_{\rm TC}$. The bead {\ct DIAMETER}, {\ct EMISSIVITY}, {\ct DENSITY}, and {\ct SPECIFIC\_HEAT} are given on the associated {\ct PROP} line. To over-ride the calculated value of the heat transfer coefficient, set {\ct HEAT\_TRANSFER\_COEFFICIENT} on the {\ct PROP} line (\si{W/(m.K)}). The default value for the bead diameter is 0.001~m. The default emissivity is 0.85. The default values for the bead density and specific heat are that of nickel; 8908~kg/m$^3$ and 0.44~kJ/kg/K, respectively. See the discussion on heat transfer to a water droplet in the Technical Reference Guide for details of the convective heat transfer to a small sphere.


\subsection{Heat Flux}
\label{info:heat_flux}

There are various output quantities related to heat flux.

\begin{labeling}{SPACE}

\item[\ct 'NET HEAT FLUX']
\hspace{1in} \newline The word {\em net} is used here to describe the sum of the emitted and absorbed radiation at a solid surface:
\be
   \dq_{\rm net}'' = \epsilon_{\rm s} \, \left( \dq_{\rm inc,rad}'' - \sigma \, T_{\rm s}^4 \right) + h \, (T_{\rm gas} - T_{\rm s}) \label{net_flux}
\ee
where $\dot{q}_{\rm inc,rad}''$ is the {\em incident} radiative heat flux, $\epsilon_{\rm s}$ is the surface emissivity, $h$ is the convective heat transfer coefficient, $T_{\rm s}$ is the surface temperature, and $T_{\rm gas}$ is the gas temperature in the vicinity of the surface.

\item[\ct 'RADIATIVE HEAT FLUX']
\hspace{1in} \newline This is the radiative component of Eq.~(\ref{net_flux}), $\quad \dq_{\rm r}'' = \epsilon_{\rm s} \, \left( \dq_{\rm inc,rad}'' - \sigma \, T_{\rm s}^4 \right)$.

\item[\ct 'CONVECTIVE HEAT FLUX']
\hspace{1in} \newline This is the convective component of Eq.~(\ref{net_flux}), $\quad \dq_{\rm c}'' = h \, (T_{\rm gas} - T_{\rm s})$.

\item[\ct 'INCIDENT HEAT FLUX']
\hspace{1in} \newline This is the term $\dq_{\rm inc,rad}''$ in Eq.~(\ref{net_flux}).

\item[\ct 'GAUGE HEAT FLUX']
\hspace{1in} \newline This quantity simulates a measurement made with a cold water heat flux gauge:
\be
   \dq_{\rm gauge}'' = \epsilon_{\rm gauge} \, \left( \dq_{\rm inc,rad}'' - \sigma \, T_{\rm gauge}^4 \right) + h \, (T_{\rm gas} - T_{\rm gauge})
\ee
If the heat flux gauge used in an experiment has a temperature other than ambient or an emissivity other than 1, use {\ct GAUGE\_TEMPERATURE} ($T_{\rm gauge}$) and {\ct GAUGE\_EMISSIVITY} ($\epsilon_{\rm gauge}$) on the {\ct PROP} line associated with the device:
\begin{lstlisting}
&DEVC ID='hf', XYZ=..., IOR=-2, QUANTITY='GAUGE HEAT FLUX', PROP_ID='hfp' /
&PROP ID='hfp', GAUGE_TEMPERATURE=80., GAUGE_EMISSIVITY=0.9 /
\end{lstlisting}
The heat transfer coefficient, $h$, is that of the solid surface to which the device is attached.

\item[\ct 'RADIOMETER']
\hspace{1in} \newline Similar to a heat flux gauge, this quantity measures only the radiative heat flux:
\be
   \dq_{\rm radiometer}'' = \epsilon_{\rm gauge} \, \left( \dq_{\rm inc,rad}'' - \sigma \, T_{\rm gauge}^4 \right)
\ee
The {\ct GAUGE\_TEMPERATURE} ($T_{\rm gauge}$) and {\ct GAUGE\_EMISSIVITY} ($\epsilon_{\rm gauge}$) can be set on the {\ct PROP} line associated with the device if their values are different than ambient and 1, respectively.

\item[\ct 'RADIATIVE HEAT FLUX GAS']
\hspace{1in} \newline All of the above heat flux output quantities are defined at a solid surface. To record the radiative heat flux away from a solid surface, add a device with the following format:
\begin{lstlisting}
&DEVC ID='hf', QUANTITY='RADIATIVE HEAT FLUX GAS', XYZ=..., ORIENTATION=-1,0,0/
\end{lstlisting}
Note that the parameter {\ct SPATIAL\_STATISTIC} is not appropriate for this quantity, meaning that you cannot integrate this quantity over a plane or volume. However, you can use the parameter {\ct POINTS} to create a one-dimensional array of heat flux gauges (see Section~\ref{info:line_file}).

\item[\ct 'RADIANCE']
\hspace{1in} \newline This is the term for the radiation intensity at the point, $\bx$, and direction angle, $\bs$, where the summation is over all spectral bands:
\be
   I(\bx,\bs) = \sum_{n=1}^N I_n(\bx,\bs)
\ee
This quantity works in a similar way to {\ct 'RADIATIVE HEAT FLUX GAS'} in that a surrogate target particle is placed at the point {\ct XYZ} with an {\ct ORIENTATION} pointing towards the source of the heat.
\begin{lstlisting}
&DEVC ID='rad2', QUANTITY='RADIANCE', XYZ=..., ORIENTATION=-1,0,0 /
\end{lstlisting}
The units for {\ct 'RADIANCE'} are kW/m$^2$/sr.

\end{labeling}


\subsection{Adiabatic Surface Temperature}
\label{info:AST}

FDS includes a calculation of the adiabatic surface temperature (AST), a quantity that is representative of the heat flux to a solid surface. Following the idea proposed by Ulf Wickstr\"{o}m~\cite{Wickstrom:Interflam2007}, $T_{\hbox{\tiny AST}}$ is the surface temperature for which the net heat flux (Eq.~(\ref{net_flux}) is zero. The following equation can be solved using an analytical solution given by Malendowski~\cite{Malendowski:FT}:
\be
   \epsilon \, \left( \dq_{\rm inc,rad}'' - \sigma \, T_{\hbox{\tiny AST}}^4 \right) + h \, (T_{\rm gas} - T_{\hbox{\tiny AST}}) = 0
\ee
where, $\dot{q}_{\rm inc,rad}''$ is the {\em incident} radiative heat flux onto the surface, $\epsilon$ is the surface emissivity, $h$ is the convective heat transfer coefficient, and $T_{\rm gas}$ is the surrounding gas temperature.

The usefulness of the AST is that it represents an effective exposure temperature that can be passed on to a more detailed model of the solid object. It provides the gas phase thermal boundary condition in a single quantity, and it is not affected by the uncertainty associated with the solid phase heat conduction model within FDS. Obviously, the objective in passing information to a more detailed model is to get a better prediction of the solid temperature (and ultimately its mechanical response) than FDS can provide. To reinforce this notion, you can output the adiabatic surface temperature even when there is no actual solid surface using the following lines:
\begin{lstlisting}
&DEVC ID='AST', XYZ=..., QUANTITY='ADIABATIC SURFACE TEMPERATURE GAS',
      ORIENTATION=0.707,0.0,0.707, PROP_ID='props' /
&PROP ID='props', EMISSIVITY=0.9, HEAT_TRANSFER_COEFFICIENT=10. /
\end{lstlisting}
This output indicates the maximum achievable solid surface temperature at the given location {\ct XYZ} that is \emph{not} actually in the vicinity of a solid surface, facing in any direction as indicated by the {\ct ORIENTATION} vector. Note that you {\em must} set the {\ct EMISSIVITY} and {\ct HEAT\_TRANSFER\_COEFFICIENT} (W/(m$^2\cdot$K)) on the {\ct PROP} line because there is no actual solid surface from which to infer these values.
In fact, FDS creates a Lagrangian particle that records the AST at the desired location. FDS creates an {\ct INIT} line to position the particle. If you want to output other quantities at this point that are related to the AST, you can create another {\ct DEVC} at the same location and use {\ct INIT\_ID} to identify the {\ct DEVC} line for the {\ct ADIABATIC SURFACE TEMPERATURE}. For example, you can output the heat transfer coefficient used in calculating the AST as follows:
\begin{lstlisting}
&DEVC ID='AST', XYZ=..., QUANTITY='ADIABATIC SURFACE TEMPERATURE GAS', ... /
&DEVC ID='HTC', XYZ=..., QUANTITY='HEAT TRANSFER COEFFICIENT', INIT_ID='AST' /
\end{lstlisting}

\subsubsection{Example: AST vs. Surface Temperature}
\label{adiabatic_surface_temperature}

The test case called {\ct adiabatic\_surface\_temperature.fds} in the {\ct Radiation} folder simulates a 0.1~mm steel plate being heated by a thermal plume. The plate is perfectly insulated ({\ct BACKING='INSULATED'} on the {\ct SURF} line) and its steady-state temperature should be equivalent to its adiabatic surface temperature or AST. The left plot of Fig.~\ref{adiabatic_surface_temperature} shows the plate temperature rising towards the AST, much as an actual plate thermometer would. The right plot simply shows the AST calculated using the {\ct QUANTITY} {\ct 'ADIABATIC SURFACE TEMPERATURE'} applied via a {\ct DEVC} at the plate surface, and the AST calculated using the {\ct QUANTITY} {\ct 'ADIABATIC SURFACE TEMPERATURE GAS'} applied via a {\ct DEVC} positioned just in front of the plate. The idea of the latter device would be to record the AST even if the plate were not actually represented in the simulation. For these two recordings of the AST to be identical, the plate {\ct SURF}ace conditions and the AST-Gas {\ct PROP}erties must both include the same explicitly-defined {\ct HEAT\_TRANSFER\_COEFFICIENT} and {\ct EMISSIVITY}.

\begin{figure}[ht]
\includegraphics[width=3in]{SCRIPT_FIGURES/adiabatic_surface_temperature}
\includegraphics[width=3in]{SCRIPT_FIGURES/adiabatic_surface_temperature_gas}
\caption[Results of the {\ct adiabatic\_surface\_temperature} test case]{(Left) Surface temperature vs. adiabatic surface temperature of an insulated plate. (Right) AST recorded with a device positioned on the plate surface (AST) and one just off the surface (AST-Gas).}
\label{adiabatic_surface_temperature_fig}
\end{figure}


\subsection{Extracting Detailed Radiation Data}
\label{info:RADF}

FDS solves the radiation transport equation (RTE) using a finite volume method in which the radiation intensity is computed over a discrete number of solid angles. Because there are approximately 100 angles by default, the angle-specific intensity values are not saved in the gas phase cells---only at boundaries. However, there is a way to save these values into a file, which might be useful for transferring data to another model or diagnosing problems with the RTE. This form of output is only appropriate when the default gray gas radiation model is used, not the narrow-band model.

Data is saved within rectangular blocks of cells using one or more input lines of the form:
\begin{lstlisting}
&RADF XB=..., I_STEP=2, J_STEP=3, K_STEP=1 /
\end{lstlisting}
This line directs FDS to write out the radiation intensity, $I_{ijk}^l$, for each cell with indices $ijk$ that is bounded by {\ct XB} and for each solid angle $l$. You can skip cells using the parameters {\ct I\_STEP}, {\ct J\_STEP}, and {\ct K\_STEP}, each of which default to 1. The print outs are done every {\ct DT\_RADF}~s starting at {\ct T\_RADF\_BEGIN} and ending at {\ct T\_RADF\_END}, where these three parameters are listed on the {\ct DUMP} line. By default, {\ct T\_RADF\_BEGIN} is set to the start time of the simulation, {\ct T\_BEGIN}, and {\ct T\_RADF\_END} is set to {\ct T\_END}. The time interval, {\ct DT\_RADF}, is the end time minus the start time divided by 5, by default.

Each output file is in text, not binary, format. The format of the file is shown in Fig.~\ref{radf_file_format}. {\ct NSTEPS} is the number of {\ct TIMES} that data is written out. {\ct NP} is the number of points within the block designated by {\ct XB} on the {\ct RADF} line of the input file. {\ct XYZ\_INTENSITIES} are the coordinates of the {\ct NP} points. {\ct NI} is the number of solid angles, which are listed under {\ct XYZ\_DIRECTIONS}. A direction vector is a normalized form of the discretized solid angle vector, $(D^l_x,D^l_y,D^l_z)$, that is described in the Radiation chapter of the FDS Technical Reference Guide, Volume 1~\cite{FDS_Math_Guide}.

Each {\ct TIME} the intensities are written out, each cell in the designated block will list its temperature in degrees~K, a placeholder value of 0, and then the intensities at the {\ct NI} solid angles in units of W/m$^2$.

\begin{figure}[p]
\begin{lstlisting}
NSTEPS
   2

TIMES
    0.00
   10.00

NP
    3150

XYZ_INTENSITIES
   2.350   1.350   0.050
   .
   .
   .

NI
 104

XYZ_DIRECTIONS
  0.138  0.138  0.981
 -0.138  0.138  0.981
 .
 .
 .

TIME
   0.00

INTENSITIES
 293.15  0.00      133.17      133.17      133.17      133.17      133.17  ...
 .
 .
 .
\end{lstlisting}
\caption[Format of {\ct RADF} output file]{Format of {\ct RADF} output file.}
\label{radf_file_format}
\end{figure}


\subsection{Detailed Spray Properties}
\label{PDPA}

Detailed experimental measurements of sprays using \underline{P}hase \underline{D}oppler \underline{P}article \underline{A}nalysis (PDPA) provide information on the droplet size distribution, speed and concentration. A special device type is defined via a {\ct DEVC} line to simulate the PDPA measurement. The actual quantity to measure, and the details of the measurement are defined using an associated {\ct PROP} line.

By default, the PDPA device output at time $t$ is computed as a time integral
\be
F(t) = \frac{1}{\min(t,t_{\rm e})-t_{\rm s}} \int_{t_{\rm s}}^{\min(t,t_{\rm e})} f(t) \, \d t
\ee
but instantaneous values can be obtained by setting {\ct PDPA\_INTEGRATE} equal to {\ct .FALSE.} on the corresponding {\ct PROP} line, in which case
\be
F(t) = f(t)
\ee
The function $f(t)$ has two forms:
\be
f_1(t) =  \left(\frac{\sum_i n_i D_i^m \, \phi}{\sum_i n_i D_i^n}\right)^{\frac{1}{m-n}}
\quad ; \quad
f_2(t) = \frac{\sum_i n_i \, \phi}{V}
\ee
where $n_i$ is the number of real particles represented by the single simulated particle, $D_i$ is the particle diameter, and $\phi$ is the quantity to be measured. In each case, the summation goes over all the particles within a sphere with radius {\ct PDPA\_RADIUS} and centered at the location given by the device {\ct XYZ}.

The first form $f_1(t)$ is used for the computation of various mean diameters, with associated properties defined using the following keywords on the {\ct PROP} line:
\begin{description}
\item[{\ct PDPA\_M}] $m$, exponent $m$ of diameter.
\item[{\ct PDPA\_N}] $n$, exponent $n$ of diameter. In case $m=n$, the exponent $1/(m-n)$ is removed from the formula.
\end{description}
The second form ($f_2(t)$) is used for the computation of mass and energy related variables that do not include the diameter weighting. The concentrations are based on the sampling volume, $V$, defined by {\ct PDPA\_RADIUS}. The quantity used for $x$ can be chosen with the keyword {\ct QUANTITY}. A summary of the available PDPA quantities is shown in Table~\ref{tbl:pdpa}.

\begin{table}[!ht]
\caption[Output quantities available for PDPA]{Output quantities available for PDPA.}
\label{tbl:pdpa}
\begin{center}
\begin{tabular}{|l|l|l|l|}
\hline
{\ct QUANTITY}              & $\phi$                                                                            & $f$    & Unit \\ \hline
{\ct 'DIAMETER'} (default)  & 1                                                                                 & $f_1$  & $\mu$m \\
{\ct 'ENTHALPY'}            & $(4/3)\rho_i r_i^3 \left(c_{p,i}(T_i)T_i-c_{p,i}(T_{\rm m})T_{\rm m} \right)$     & $f_2$  & kJ/m$^3$ \\
{\ct 'PARTICLE FLUX X'}     & $(4/3)\rho_i r_i^3 u_i$                                                           & $f_2$  & kg/m$^2$s \\
{\ct 'PARTICLE FLUX Y'}     & $(4/3)\rho_i r_i^3 v_i$                                                           & $f_2$  & \si{kg/(m$^2$.s)} \\
{\ct 'PARTICLE FLUX Z'}     & $(4/3)\rho_i r_i^3 w_i$                                                           & $f_2$  & \si{kg/(m$^2$.s)} \\
{\ct 'U-VELOCITY'}          & $u_i$                                                                             & $f_1$  & m/s \\
{\ct 'V-VELOCITY'}          & $v_i$                                                                             & $f_1$  & m/s \\
{\ct 'W-VELOCITY'}          & $w_i$                                                                             & $f_1$  & m/s \\
{\ct 'VELOCITY'}            & $(u_i^2+v_i^2+w_i^2)^{\ha}$                                                       & $f_1$  & m/s \\
{\ct 'TEMPERATURE'}         & $T_i$                                                                             & $f_1$  & ${}^\circ$C \\
{\ct 'MASS CONCENTRATION'}  & $(4/3)\rho r_i^3 $                                                                & $f_2$  & kg/m$^3$ \\
{\ct 'NUMBER CONCENTRATION'}& 1                                                                                 & $f_2$  & \\
 \hline
\end{tabular}
\end{center}
${}^*$ $T_{\rm m}$ is the melting temperature of the associated species.
\end{table}

It is also possible to output histograms of PDPA output quantities. When {\ct PDPA\_HISTOGRAM} is set to {\ct .TRUE.}, normalized histogram bin counts are output to a comma-separated value (.csv) file from all devices associated with this {\ct PROP} line. The number of bins and the limits of the histogram are controlled by parameters on the {\ct PROP} line. The value used in creating the histogram is $D_i^m \; \phi$. Note that when making a histogram of diameters, the limits must be given in meters, not microns. Values falling outside the histogram limits are included in the counts of the first and last bins. Cumulative distributions can be output by setting {\ct PDPA\_HISTOGRAM\_CUMULATIVE=.TRUE.} on the {\ct PROP} line. To output unnormalized counts or cumulative distribution, set {\ct PDPA\_NORMALIZE} to {\ct .FALSE.}. Note, however, that the counts correspond to the super droplets/particles, not the numerical ones. Due to the stratified sampling technique used (see Section~\ref{info:particle_size}), the counts are not necessarily integers.

The histogram output file contains of two-columns for each device. The first column gives the bin centers, and the second column gives the relative frequency. Volume and area based distributions can be output by setting the {\ct PDPA\_N} parameter on the {\ct PROP} line to {\ct 3} and {\ct 2} respectively. Notice that this works differently from the mean diameter computation where the weighting is based on the {\ct PDPA\_M} parameter.

The properties of the PDPA device are defined using the following keywords on the {\ct PROP} line:
\begin{description}
\item[{\ct PART\_ID}] Name of the particle group to limit the computation to. Do not specify to account for all particles.
\item[{\ct PDPA\_START}] $t_{\rm s}$, starting time of time integration in seconds. PDPA output is always a running average over time. As the spray simulation may contain some initial transient phase, it may be useful to specify the starting time of data collection.
\item[{\ct PDPA\_END}] $t_{\rm e}$, ending time of time integration in seconds.
\item[{\ct PDPA\_INTEGRATE}] A logical parameter for choosing between time integrated or instantaneous values. {\ct .TRUE.} by default.
\item[{\ct PDPA\_RADIUS}] Radius (m) of the sphere, centered at the device location, inside which the particles are monitored.
\item[{\ct PDPA\_NORMALIZE}] Can be set {\ct .FALSE.} to force $V = 1$ in the formula for $f_2(t)$, or to unnormalize the histogram output.
\item[{\ct QUANTITY}] Specified on {\ct PROP} line for choosing the variable $\phi$.
\item[{\ct PDPA\_HISTOGRAM\_NBINS}] Number of bins used for the histogram.
\end{description}
The following example is used to measure the Sauter mean diameter, $D_{32}$, of the particle type {\ct 'water drops'}, starting from time 5~s.
\begin{lstlisting}
&PROP ID='pdpa_d32'
      PART_ID='water drops'
      PDPA_M=3
      PDPA_N=2
      PDPA_RADIUS=0.01
      PDPA_START=5. /
&DEVC XYZ=0.0,0.0,1.0, QUANTITY='PDPA', PROP_ID='pdpa_d32' /
\end{lstlisting}
The following example is used to write out a histogram of droplet size using 20 equally sized bins between 0 and 2000 $\mu$m.
\begin{lstlisting}
&PROP ID='pdpa_d'
      PART_ID='water drops'
      QUANTITY="DIAMETER"
      PDPA_RADIUS=0.01
      PDPA_START=0.0
      PDPA_M=1
      PDPA_HISTOGRAM=.TRUE.
      PDPA_HISTOGRAM_NBINS=20
      PDPA_HISTOGRAM_LIMITS=0,2000E-6 /
&DEVC XYZ=0.0,0.0,1.0, QUANTITY='PDPA', PROP_ID='pdpa_d' /
\end{lstlisting}






\subsection{Output Associated with Thermogravimetric Analysis (TGA)}
\label{info:material_components}

In addition to the profile ({\ct PROF}) output, there are various additional quantities that are useful for monitoring reacting surfaces. For example, {\ct 'WALL THICKNESS'} gives the overall thickness of the solid surface element. {\ct 'SURFACE DENSITY'} gives the overall mass per unit area for the solid surface element, computed as an integral of material density over wall thickness. Both quantities are available both as {\ct DEVC} and {\ct BNDF}. For the quantity {\ct 'SURFACE DENSITY'}, you can add a {\ct MATL\_ID} to get the surface density of a single component of the solid material.

\subsubsection{Thermogravimetric Analysis (TGA) Output}

Thermogravimetric Analysis or TGA is a bench-scale measurement in which a very small solid material sample is heated up at a constant rate. The results of a TGA measurement are presented in the form of a normalized mass and normalized mass loss rate. Analogous quantities can be output from FDS:
\begin{eqnarray*}
   \hbox{\ct 'NORMALIZED MASS'} &=& \sum_\alpha  m''_\alpha (t) \Big/ \sum_\alpha  m''_\alpha (0) \quad \quad \hbox{(dimensionless)} \\
   \hbox{\ct 'NORMALIZED MASS LOSS RATE'} &=& \sum_\alpha  \dot{m}''_\alpha (t) \Big/ \sum_\alpha  m''_\alpha (0)  \quad \quad \left( \si{1/s} \right)
\end{eqnarray*}
For both of these quantities, you can add a {\ct MATL\_ID} to get the normalized mass or mass loss rate of a single component of the solid material, $m''_\alpha (t) / \sum_\alpha  m''_\alpha (0)$.

\subsubsection{Micro-Combustion Calorimetry (MCC) Output}

Micro-Combustion Calorimetry or MCC is similar to TGA, except the vaporized gas is burned. The result is a normalized heat release rate:
\begin{equation*}
   \hbox{\ct 'NORMALIZED HEAT RELEASE RATE'} =  \dot{m}''_f (t) \, \Delta H \Big/ \sum_\alpha  m''_\alpha (0) \quad \quad \hbox{(W/g)}
\end{equation*}
Note that $\dot{m}''_{\rm F}$ is the mass flux of fuel and $\Delta H$ is the heat of combustion.


\subsubsection{Differential Scanning Calorimetry (DSC) Output}

Differential Scanning Calorimetry or DSC is a measurement of the rate of heat absorption by a small material sample under constant heating. The result is a normalized heat absorption rate:
\begin{equation*}
   \hbox{\ct 'NORMALIZED HEATING RATE'} =  \dot{q}''_{\rm c} (t) \Big/ \sum_\alpha  m''_\alpha (0) \quad \quad \hbox{(W/g)}
\end{equation*}
Note that it is assumed that the sample is heated purely by convection, in which case $\dot{q}_{\rm c}''$ is the convective heat flux.








\subsection{Fractional Effective Dose (FED) and Fractional Irritant Concentration (FIC)}
\label{info:FED}

The Fractional Effective Dose index (FED), developed by Purser~\cite{SFPE:Purser}, is a commonly used measure of human incapacitation
due to the combustion gases. The FED value is calculated as
\be
\mathrm{FED}_\mathrm{tot} = (\mathrm{FED}_\mathrm{CO} + \mathrm{FED}_\mathrm{CN} + \mathrm{FED}_\mathrm{NO_x} + \mathrm{FLD}_\mathrm{irr}) \times \mathrm{HV}_\mathrm{CO_2} + \mathrm{FED}_\mathrm{O_2}
\ee
The fraction of an incapacitating dose of CO is calculated as
\be
\mathrm{FED}_\mathrm{CO} = \int_0^t 2.764 \times 10^{-5} \, (C_\mathrm{CO}(t))^{1.036} \, \d t
\ee
where $t$ is time in minutes and $C_\mathrm{CO}$ is the CO concentration (ppm). The fraction of an incapacitating dose of CN is calculated as
\be
\mathrm{FED}_\mathrm{CN} = \mathlarger{\int}_0^t \left( \frac{1}{220} \; \exp \left( \frac{C_\mathrm{CN}(t)}{43} \right) - 0.0045 \right) \, \d t
\ee
where $t$ is time in minutes and $C_\mathrm{CN}$ is the concentration (ppm) of HCN corrected for the protective effect of NO$_\mathrm{2}$. $C_\mathrm{CN}$ is calculated as
\be
C_\mathrm{CN} = C_\mathrm{HCN} - C_\mathrm{NO_2} - C_\mathrm{NO}
\ee
The fraction of an incapacitating dose of NO$_x$ is calculated as
\be
\mathrm{FED}_\mathrm{NO_x} = \int_0^t \frac{C_\mathrm{NO_x}(t)}{1500} \, \d t
\ee
where $t$ is time in minutes and $C_\mathrm{NO_x}$ is the sum of NO and NO$_\mathrm{2}$ concentrations (ppm).

The Fractional Lethal Dose (FLD) of irritants is calculated as
\be
\mathrm{FLD}_\mathrm{irr} = \int_0^t \left(
    \frac{C_\mathrm{HCl}(t)}    {F_\mathrm{FLD,HCl}} +
    \frac{C_\mathrm{HBr}(t)}    {F_\mathrm{FLD,HBr}} +
    \frac{C_\mathrm{HF}(t)}     {F_\mathrm{FLD,HF}} +
    \frac{C_\mathrm{SO_2}(t)}   {F_\mathrm{FLD,SO_2}} +
    \frac{C_\mathrm{NO_2}(t)}   {F_\mathrm{FLD,NO_2}} +
    \frac{C_\mathrm{C_3H_4O}(t)}{F_\mathrm{FLD,C_3H_4O}} +
    \frac{C_\mathrm{CH_2O}(t)}  {F_\mathrm{FLD,CH_2O}}
    \right) \, \d t
\ee
where $t$ is time in minutes, the nominators are the instantaneous concentrations (ppm) of each irritant and
the denominators are the exposure doses of respective irritants predicted to be lethal to half the population.
The lethal exposure doses~\cite{SFPE:Purser} are given in Table~\ref{tbl:FIC}. To include the effect of an irritant gas not listed in the table,
you should specify $\mathrm{F_{FLD}}$ in ppm$\times$min using the {\ct FLD\_LETHAL\_DOSE} property of the corresponding {\ct SPEC} line.
\begin{table}[ht]
\caption[Coefficients used for the computation of irritant effects of gases]{Coefficients used for the computation of irritant effects of gases.}
\label{tbl:FIC}
\begin{center}
\begin{tabular}{|l|l|l|l|l|l|l|l|}
\hline & HCl & HBr & HF & $\mathrm{SO_2}$ & $\mathrm{NO_2}$ & $\mathrm{C_3H_4O}$ & $\mathrm{CH_2O}$  \\ \hline \hline
F${}_\mathrm{FLD}$ (ppm $\times$ min) & 114000 & 114000 & 87000 & 12000 & 1900 & 4500 & 22500 \\
F${}_\mathrm{FIC}$ (ppm) & 900 & 900 & 900 & 120 & 350 & 20 & 30 \\ \hline
\end{tabular}
\end{center}
\end{table}

The fraction of an incapacitating dose of low O${}_2$ hypoxia is calculated as
\be
\mathrm{FED}_\mathrm{O_2} =  \int_0^t \frac{\d t}{\exp \left [ 8.13 - 0.54 \, (20.9 - C_\mathrm{O_2}(t)) \right ] }
\ee
where $t$ is time in minutes and $C_\mathrm{O_2}$ is the O${}_2$ concentration (volume percent).
The hyperventilation factor induced by carbon dioxide is calculated as
\be
\mathrm{HV}_\mathrm{CO_2} = \frac{ \exp( 0.1903 \, C_\mathrm{CO_2}(t) +  2.0004 ) }{7.1} \label{co2hyp}
\ee
where $t$ is time in minutes and $C_\mathrm{CO_2}$ is the CO${}_2$ concentration (percent).

The Fractional Irritant Concentration (FIC), also developed by Purser~\cite{SFPE:Purser}, represents the toxic effect which
depends upon the immediate concentrations of irritants. The overall irritant concentration FIC is calculated as
\be
\mathrm{FIC}_\mathrm{irr} =
    \frac{C_\mathrm{HCl}(t)}    {F_\mathrm{FIC,HCl}} +
    \frac{C_\mathrm{HBr}(t)}    {F_\mathrm{FIC,HBr}} +
    \frac{C_\mathrm{HF}(t)}     {F_\mathrm{FIC,HF}} +
    \frac{C_\mathrm{SO_2}(t)}   {F_\mathrm{FIC,SO_2}} +
    \frac{C_\mathrm{NO_2}(t)}   {F_\mathrm{FIC,NO_2}} +
    \frac{C_\mathrm{C_3H_4O}(t)}{F_\mathrm{FIC,C_3H_4O}} +
    \frac{C_\mathrm{CH_2O}(t)}  {F_\mathrm{FIC,CH_2O}}
\ee
where the nominators are the instantaneous concentrations of each irritant and the denominators are the concentrations of respective irritants
expected to cause incapacitation in half the population. The incapacitating concentrations~\cite{SFPE:Purser} are given in Table~\ref{tbl:FIC}.
To include the irritant effect of a gas not listed in the table, you should specify $\mathrm{F_{FIC}}$ in ppm using the {\ct FIC\_CONCENTRATION}
property on the corresponding {\ct SPEC} line.

Note that the spatial integration features (Section~\ref{info:statistics}) cannot be used with FED output because FED makes
use of the {\ct 'TIME INTEGRAL'} statistic (Section~\ref{info:time_integral}). For the same reason, FED output is only available as a point measurement.

In order to view the FED slice file in smokeview, CO, CO${}_2$ and O${}_2$ slice files need to be defined in the input file as in the example below:

\begin{lstlisting}
&SLCF PBY= 1.0, QUANTITY='VOLUME FRACTION', SPEC_ID= 'CARBON DIOXIDE' /
&SLCF PBY= 1.0, QUANTITY='VOLUME FRACTION', SPEC_ID= 'CARBON MONOXIDE' /
&SLCF PBY= 1.0, QUANTITY='VOLUME FRACTION', SPEC_ID= 'OXYGEN' /
\end{lstlisting}


\subsection{Spatially-Integrated Outputs}
\label{info:statistics}

A useful feature of a device ({\ct DEVC}) is to specify an output quantity along with a desired statistic. For example,
\begin{lstlisting}
&DEVC XB=..., QUANTITY='TEMPERATURE', ID='maxT', SPATIAL_STATISTIC='MAX' /
\end{lstlisting}
causes FDS to write out the maximum gas phase temperature over the volume bounded by {\ct XB}. Note that it does not compute the maximum over the entire computational domain, just the specified volume, and this volume must lie within a single mesh. Other {\ct SPATIAL\_STATISTIC}'s are discussed below.  Note that some are appropriate for gas phase output quantities, some for solid phase, and some for both.

For solid phase output quantities, like heat fluxes and surface temperatures, the specification of a {\ct SURF\_ID} along with the appropriate statistic limits the calculation to only those surfaces. You can further limit the search by using the sextuplet of coordinates {\ct XB} to force FDS to only compute statistics for surface cells within the given volume. Be careful to account for the fact that the solid surface might shift to conform to the underlying numerical grid. Also, be careful not to specify a volume that extends beyond a single mesh. Note that you do not (and should not) specify an orientation via the parameter {\ct IOR} when using a spatial statistic. {\ct IOR} is only needed to find a specific point on the solid surface.


\subsubsection{Minimum or Maximum Value}

For a gas phase scalar quantity defined at the center of each grid cell, $\phi_{ijk}$, set {\ct SPATIAL\_STATISTIC} to {\ct ='MIN'} or {\ct 'MAX'} to compute the minimum or maximum value, respectively, over the cells that are included in the specified volume bounded by {\ct XB}:
\be
   \min_{ijk} \, \phi_{ijk} \quad ; \quad  \max_{ijk} \, \phi_{ijk}
\ee
Note that this statistic is only appropriate for gas phase quantities. Note also that you must specify a volume to sum over via the coordinate parameters, {\ct XB}, which can extend into multiple meshes.


\subsubsection{Average Value}

For a gas phase scalar quantity defined at the center of each grid cell, $\phi_{ijk}$, the {\ct SPATIAL\_STATISTIC} {\ct 'MEAN'} computes the average value,
\be \frac{1}{N} \; \sum_{ijk} \phi_{ijk}  \ee
over the cells that are included in the specified volume bounded by {\ct XB}. Note that this statistic is only appropriate for gas phase quantities. Note also that you must specify a volume to sum over via the coordinate parameters, {\ct XB}, which can extend into multiple meshes.

\subsubsection{Volume-Weighted Mean}

For a gas phase scalar quantity, $\phi(x,y,z)$, {\ct SPATIAL\_STATISTIC='VOLUME MEAN'} produces the discrete analog of
\be \frac{1}{V} \; \int \phi(x,y,z) \; \d x \, \d y \, \d z \ee
which is very similar to {\ct 'MEAN'}, but it weights the values according to the relative size of the mesh cell. Note that this statistic is only appropriate for gas phase quantities. Note also that you must specify a volume to sum over via the coordinate parameters, {\ct XB}, which can extend into multiple meshes.

\subsubsection{Mass-Weighted Mean}

For a gas phase scalar quantity, $\phi(x,y,z)$, {\ct SPATIAL\_STATISTIC='MASS MEAN'} produces the discrete analog of
\be \frac{ \int \rho(x,y,z) \; \phi(x,y,z) \; \d x \, \d y \, \d z}{\int \rho \; \d x \, \d y \, \d z}  \ee
which is similar to {\ct 'VOLUME MEAN'}, but it weights the values according to the relative mass of the mesh cell. Note that this statistic is only appropriate for gas phase quantities. Note also that you must specify a volume to sum over via the coordinate parameters, {\ct XB}, which can extend into multiple meshes.

\subsubsection{Volume Integral}

For a gas phase scalar quantity, $\phi(x,y,z)$, {\ct SPATIAL\_STATISTIC='VOLUME INTEGRAL'} produces the discrete analog of
\be \int \phi(x,y,z) \; \d x \, \d y \, \d z \ee
This statistic is only appropriate for gas phase quantities, in particular those whose units involve m$^{-3}$. For example, heat release rate per unit volume is an appropriate output quantity. This statistic can also be used on a {\ct DEVC} line with an output quantity of {\ct DENSITY} to output the total mass within the volume bound by {\ct XB}. In all cases, you must specify a volume to sum over via the coordinate parameters, {\ct XB}, which can extend into multiple meshes.

\subsubsection{Mass Integral}

For a given gas phase output quantity, $\phi(x,y,z)$, {\ct SPATIAL\_STATISTIC='MASS INTEGRAL'} produces the discrete analog of
\be \int \, \rho(x,y,z) \; \phi(x,y,z) \; \d x \, \d y \, \d z \ee
Note that this statistic is only appropriate for gas phase quantities. Note also that you must specify a volume to sum over via the coordinate parameters, {\ct XB}, which can extend into multiple meshes.

\subsubsection{Area Integral}

For a gas phase scalar quantity, $\phi(x,y,z)$, {\ct SPATIAL\_STATISTIC='AREA INTEGRAL'} produces the discrete analog of
\be \int \phi(x,y,z) \; \d A \ee
where $dA$ depends on the coordinates you specify for {\ct XB}. Note that this statistic is only appropriate for gas phase quantities, in particular those whose units involve m$^{-2}$. For example,
the quantity {\ct 'MASS FLUX X'} along with {\ct SPEC\_ID='my gas'} is an appropriate output quantity if you want to know the mass flux of the gas species that you have named {\ct 'my gas'} through an
area normal to the $x$ direction. Note also that you must specify an area to sum over via the coordinate parameters, {\ct XB}, which can extend into multiple meshes.

\subsubsection{Surface Integral}

For a solid phase scalar quantity, $\phi$, {\ct SPATIAL\_STATISTIC='SURFACE INTEGRAL'} produces the discrete analog of
\be \int \phi \; \d A \ee
Note that this statistic is only appropriate for solid phase quantities, in particular those whose units involve m$^{-2}$. For example, the various heat and mass fluxes are appropriate output quantities.

\subsubsection{Limiting the Integration}

The input parameter {\ct QUANTITY\_RANGE} can be used to limit the region of integration for {\ct 'AREA INTEGRAL'}, {\ct 'VOLUME INTEGRAL'}, {\ct 'MASS INTEGRAL'}, and {\ct 'SURFACE INTEGRAL'}.  If {\ct QUANTITY\_RANGE} is set, the integration will only be performed if the value of the {\ct QUANTITY} lies within the {\ct QUANTITY\_RANGE} where {\ct QUANTITY\_RANGE(1)} is the lower bound and {\ct QUANTITY\_RANGE(2)} is the upper bound.  For example:
\begin{lstlisting}
&DEVC XB=..., QUANTITY='MASS FRACTION', SPEC_ID='METHANE', SPATIAL_STATISTIC='MASS INTEGRAL', QUANTITY_RANGE=0.03,0.15/
\end{lstlisting}
would output the total mass of methane in the volume {\ct XB} where the mass fraction was between 0.03 and 0.15.

A set of additional {\ct SPATIAL\_STATISTIC}'s are available for use with {\ct QUANTITY\_RANGE}: {\ct 'MASS'}, {\ct 'VOLUME'}, and {\ct 'SURFACE AREA'}.  These output the mass, volume, or surface area (for a solid phase quantity) where the {\ct QUANTITY} lies within the {\ct QUANTITY\_RANGE}.  For example:
\begin{lstlisting}
&DEVC XB=..., QUANTITY='NET HEAT FLUX', SPATIAL_STATISTIC='SURFACE AREA', QUANTITY_RANGE(1)=10./
\end{lstlisting}
would output the total surface area in the volume {\ct XB} where the net heat flux exceeds 10~kW/m$^2$.

\subsubsection{Volume, Mass, and Heat Flow}
\label{info:flows}

The net flow of mass and energy into or out of a planar surface can be a useful diagnostic. There are several outputs that address these. All are prescribed via the device ({\ct DEVC}) namelist group only. For example:
\begin{lstlisting}
&DEVC XB=0.3,0.5,2.1,2.5,3.0,3.0, QUANTITY='MASS FLOW', ID='whatever' /
\end{lstlisting}
outputs the net integrated mass flux through the given planar area, oriented in the positive $z$ direction, in this case. The three flows {\ct 'VOLUME FLOW'}, {\ct 'MASS FLOW'}, and {\ct 'HEAT FLOW'} are defined:
\begin{align}
\dot{V} &= \int \bu \cdot \d \mathbf{S}  \\
\dot{m} &= \int \rho \bu \cdot \d \mathbf{S} \\
\dot{q} &= \int \rho c_p (T-T_\infty) \, \bu \cdot \d \mathbf{S}
\end{align}
The addition of a {\ct +} or {\ct -} to the {\ct QUANTITY} names yields the integral of the flow in the positive or negative direction only. In other words, if you want to know the mass flow out of a compartment, use {\ct 'MASS FLOW +'} or {\ct 'MASS FLOW -'}, depending on the orientation of the door.

\subsubsection{Volume, Mass, and Heat Flow at a Wall}
\label{info:wallflows}

The quantities {\ct 'VOLUME FLOW'}, {\ct 'MASS FLOW'}, and {\ct 'HEAT FLOW'} cannot be applied at a solid boundary.  Instead, use the wall equivalents {\ct 'VOLUME FLOW WALL'}, {\ct 'MASS FLOW WALL'}, and {\ct 'HEAT FLOW WALL'}.  These quantities require an {\ct IOR} for the surface (positive points into the domain).  If you want the mass flow of a particular gas species, include the {\ct SPEC\_ID} of that gas species. Note that, in order to be a more useful diagnostic for global energy balances, the heat flow at the wall is defined using the sensible enthalpy of the mixture (composition taken at the wall) and is not relative to ambient conditions:
\be
\dot{q}_{\mathrm{w}} = \int \rho h_s(T) \, \bu \cdot \d \mathbf{S}
\ee

\subsubsection{Mass Flux at a Boundary}
\label{info:wallflux}

There are two quantities that may be used for measuring mass flux on boundaries: {\ct 'MASS FLUX'} and {\ct 'MASS FLUX WALL'}.  Each takes a {\ct SPEC\_ID} if a certain species is desired.  If {\ct SPEC\_ID} is omitted, then the total flux is given.  The difference between the two outputs is that {\ct 'MASS FLUX'} has been designed primarily to work with the solid phase solver, and only provides mass fluxes at a solid surface.  Those fluxes may have been specified by the user on a {\ct SURF} line or computed by the pyrolysis model.

The purpose of {\ct 'MASS FLUX WALL'} is for generating detailed species mass balances including flows in and out of the domain at {\ct OPEN} boundaries.  The value of the flux for species $\alpha$ is $\rho Y_\alpha u_n - \rho D_\alpha \partial Y_\alpha / \partial n$ where $\mathbf{n}$ is the normal direction of the surface.  The convention used here is that positive fluxes are entering the domain and negative fluxes are leaving. The quantity may be applied at a solid surface, a flow vent, or an {\ct OPEN} boundary.  When used in conjunction with {\ct MASS\_FILE=.TRUE.} on {\ct DUMP}, a tight species mass balance should be obtainable.


\subsection{Temporally-Integrated Outputs}
\label{info:time_integral}

In addition to the spatial statistics, temporal statistics can be applied to {\ct DEVC} output via the parameter {\ct TEMPORAL\_STATISTIC}. Both {\ct SPATIAL\_STATISTIC} and {\ct TEMPORAL\_STATISTIC} can be specified simultaneously on the {\ct DEVC} line, assuming the combination makes sense. The {\ct SPATIAL\_STATISTIC} is applied first, say an integration of the {\ct QUANTITY} over a given volume {\ct XB}, followed by the {\ct TEMPORAL\_STATISTIC}, like a time integral.

\subsubsection{Time Average}

The {\ct TEMPORAL\_STATISTIC='TIME AVERAGE'} is typically applied by default, unless it is inappropriate for the chosen {\ct QUANTITY}. With this statistic, FDS outputs the average value of the {\ct QUANTITY} over the time period of {\ct DT\_DEVC}~s just prior to the time of output. The parameter {\ct DT\_DEVC} is specified on the {\ct DUMP} line.

\subsubsection{Running Average}

The {\ct TEMPORAL\_STATISTIC='RUNNING AVERAGE'} outputs the running average value of the {\ct QUANTITY} over the time period starting at {\ct STATISTICS\_START} and ending at {\ct STATISTICS\_END}. This is the default behavior of ``line'' devices discussed in Section~\ref{info:line_file}.

\subsubsection{Instantaneous Value}

For various reasons you might want to output the value of the {\ct QUANTITY} that has not been time-averaged or processed in any way. Sometimes this is important for device and control functions. To output the instantaneous value, set {\ct TEMPORAL\_STATISTIC} to {\ct 'INSTANT VALUE'}.

\subsubsection{Time Integral}

{\ct TEMPORAL\_STATISTIC='TIME INTEGRAL'} produces a discrete analog of the time integral:
\be
 \int_{t_0}^t \phi(\tau) \; \d \tau
\ee

\subsubsection{Minimum and Maximum Values over Time}

Set {\ct TEMPORAL\_STATISTIC} to {\ct 'MIN'} or {\ct 'MAX'} to determine the minimum or maximum value of the {\ct QUANTITY} over a time interval:
\be
   \min_{t_0<=t<=t_1} \phi(t) \quad ; \quad  \max_{t_0<=t<=t_1} \phi(t)
\ee
where $t_0$ is {\ct STATISTICS\_START} and $t_1$ is {\ct STATISTICS\_END}.

For some applications you might need to predict a minimum or maximum value of the {\ct QUANTITY} over a time interval that is longer than the simulation time. For example, in wind engineering the so-called 50~year maximum wind speed can be estimated using maximum yearly values collected over, say, 10~years. The idea is that extreme values conform to certain statistical distributions from which one can extrapolate extreme values over long time periods. In FDS, you can do something similar. If you add the parameter {\ct TIME\_PERIOD} to the {\ct DEVC} line where you have also set the {\ct TEMPORAL\_STATISTIC} to {\ct 'MIN'} or {\ct 'MAX'}, the time interval bounded by $t_0$ and $t_1$ is subdivided into $N=${\ct N\_INTERVALS} (default 10), and a minimum or maximum value is stored for each interval. At the end of the simulation, the set of maximum values (minimum values are handled similarly) are ranked in ascending order, $m=1,N$. Next, the cumulative statistical distribution is introduced~\cite{Harris:JWE1996}:
\be
   F(\phi) = 1 - \exp[-\exp(\phi)]  \quad ; \quad  \phi = \ln[-\ln(1-F)]
\ee
which represents the probability\footnote{Note that the parameterless form of the distribution is intended for extrapolation only.} of the value $\phi$ not being exceeded in the given time interval, $(t_1-t_0)/N$. The probabilities for each of the $N$ ascending maximum values are assumed to be $m/(N+1)$. Plotting $\phi$ versus the expression on the right yields an approximate straight line from which we can estimate the value of $\phi$ appropriate for the longer {\ct TIME\_PERIOD}; that is, the value for which the probability of not being exceeded in the relatively short time interval $(t_1-t_0)/N$ is very close to 1. Returning to the example from wind engineering, the probability of not exceeding the 50~year wind speed in a given year is $1-1/50=0.98$.

\subsubsection{Root Mean Square}
\label{info:rms}
\label{info:rmscovcorr}

{\ct TEMPORAL\_STATISTIC='RMS'} produces the unbiased estimate of the {\em root mean square} of the {\ct QUANTITY} $\phi$:
\be
   \phi_{\rm rms} = \sqrt{ \frac{ \sum_{i=1}^n (\phi_i - \overline{\phi})^2 }{n-1} }
\ee
The computation starts at {\ct STATISTICS\_START} and ends at {\ct STATISTICS\_END}.

\subsubsection{Covariance}
\label{info:covariance}

If $u = U - \overline{U}$ and $v= V-\overline{V}$ are the deviations for two random variables, $U$ and $V$, then an unbiased estimate of the \emph{covariance} is given by
\be
   \overline{u\, v} = \frac{ \sum_{i=1}^n (U_i - \overline{U}) (V_i - \overline{V}) }{n-1}
\ee
To output this statistic you must add a {\ct QUANTITY2} to the {\ct DEVC} line and set {\ct TEMPORAL\_STATISTIC='COV'}.  The following lines would create a line of devices and a single point device equivalent to the first point in the line:
\begin{lstlisting}
&DEVC XB=X1,X2,Y1,Y2,Z1,Z2, QUANTITY='CELL W', QUANTITY2='TEMPERATURE',
      TEMPORAL_STATISTIC='COV', ID='wT-cov_line', POINTS=20 /
&DEVC XYZ=X1,Y1,Z1, QUANTITY='CELL W', QUANTITY2='TEMPERATURE',
      TEMPORAL_STATISTIC='COV', ID='wT-cov_point', STATISTICS_START=20. /
\end{lstlisting}

\subsubsection{Correlation Coefficient}
\label{info:corrcoef}

Setting {\ct TEMPORAL\_STATISTIC='CORRCOEF'} outputs the \emph{correlation coefficient} given by
\be
   \rho_{uv} = \frac{ \overline{u\, v} }{ u_{\rm rms} \,v_{\rm rms} }
\ee
Here again you must add a {\ct QUANTITY2} to the device line.

\subsection{Wind and the Pressure Coefficient}
\label{info:pressure_coefficient}

In the field of wind engineering, a commonly used quantity is known as the {\ct PRESSURE\_COEFFICIENT}:
\be
   C_p = \frac{p-p_\infty}{\ha \rho_\infty U^2}
\ee
$p_\infty$ is the ambient, or ``free stream'' pressure, and $\rho_\infty$ is the ambient density.  The parameter $U$ is the free-stream wind speed, given as {\ct CHARACTERISTIC\_VELOCITY} on the {\ct PROP} line
\begin{lstlisting}
&BNDF QUANTITY='PRESSURE COEFFICIENT', PROP_ID='U' /
&DEVC ID='pressure tap', XYZ=..., IOR=2, QUANTITY='PRESSURE COEFFICIENT', PROP_ID='U' /
&PROP ID='U', CHARACTERISTIC_VELOCITY=3.4 /
\end{lstlisting}
Thus, you can either paint values of $C_p$ at all surface points, or create a single time history of $C_p$ using a single device at a single point.


\subsection{Dry Volume and Mass Fractions}
\label{info:dry}

During actual experiments, species such as CO and CO$_2$ are typically measured ``dry''; that is, the water vapor is removed from the gas sample prior to analysis.  For easier comparison of FDS predictions with measured data,
you can specify the logical parameter {\ct DRY} on a {\ct DEVC} line that reports the {\ct 'MASS FRACTION'} or {\ct 'VOLUME FRACTION'} of a species.  For example, the first line reports the actual volume fraction of CO, and the second line reports the output of a gas analyzer in a typical experiment.

\begin{lstlisting}
&DEVC ID='wet CO', XYZ=..., QUANTITY='VOLUME FRACTION', SPEC_ID='CARBON MONOXIDE'/
&DEVC ID='dry CO', XYZ=..., QUANTITY='VOLUME FRACTION', SPEC_ID='CARBON MONOXIDE',
      DRY=.TRUE. /
\end{lstlisting}


\subsection{Aerosol and Soot Concentration}
\label{info:soot}

Currently there are three different device options for outputting aerosol concentration (e.g., soot concentration) from FDS. It is important to recognize what each device is outputting so that the proper selection can be made.

\begin{lstlisting}
&DEVC ID='MF_SOOT', XYZ=..., QUANTITY='MASS FRACTION', SPEC_ID='SOOT'/
&DEVC ID='VF_SOOT', XYZ=..., QUANTITY='VOLUME FRACTION', SPEC_ID='SOOT'/
&DEVC ID='SOOT_VF', XYZ=..., QUANTITY='AEROSOL VOLUME FRACTION', SPEC_ID='SOOT'/
\end{lstlisting}

\noindent Specifying a {\ct DEVC} with a {\ct 'MASS FRACTION'} and a {\ct SPEC\_ID} of {\ct SOOT} will output the mass fraction of soot in the gas phase. The quantity {\ct 'VOLUME FRACTION'} and a {\ct SPEC\_ID} of {\ct SOOT} will output the volume fraction of soot in the gas phase treating the soot as if it were an ideal gas. The quantity {\ct 'AEROSOL VOLUME FRACTION'} and a {\ct SPEC\_ID} of {\ct SOOT} will output the volume fraction of soot as if it were a solid particle in the computational cell based on the following equation,

\begin{equation}\label{eq:soot_volume_fraction}
f_v = \rho Y_{\rm a} / \rho_{\rm a}
\end{equation}
\noindent where $\rho$ is the local density, $Y_{\rm a}$ is the local mass fraction of the aerosol, and $\rho_{\rm a}$ is density of the aerosol defined using the {\ct SPEC} input {\ct DENSITY\_SOLID}, which defaults to 1800~(kg/m$^3$) for soot.

\subsection{Gas Velocity}
\label{info:velocity}

The gas velocity components, $u$, $v$, and $w$, can be output as slice ({\ct SLCF}), point device ({\ct DEVC}), isosurface ({\ct ISOF}), or Plot3D quantities using the names {\ct 'U-VELOCITY'}, {\ct 'V-VELOCITY'}, and {\ct 'W-VELOCITY'}. The total velocity is specified as just {\ct 'VELOCITY'}. Normally, the velocity is always positive, but you can use the parameter {\ct VELO\_INDEX} with a value of 1, 2 or 3 to indicate that the velocity ought to have the same sign as $u$, $v$, or $w$, respectively. This is handy if you are comparing velocity predictions with measurements. For Plot3D files, add {\ct PLOT3D\_VELO\_INDEX(N)=...} to the {\ct DUMP} line, where {\ct N} refers to the Plot3D quantity 1, 2, 3, 4 or 5.


\subsection{Enthalpy}
\label{info:enthalpy}

There are several outputs that report the enthalpy of the gas mixture. First, the {\ct 'SPECIFIC ENTHALPY'} and the {\ct 'SPECIFIC SENSIBLE ENTHALPY'} are defined:
\be
   h(T) = \Delta h^\circ_{\rm f} + \int_{T_{\rm ref}}^{T} c_p(T') \, \d T'  \quad ; \quad h_{\rm s}(T) = \int_{T_{\rm ref}}^{T} c_p(T') \, \d T'
\ee
Both have units of kJ/kg. The quantities {\ct 'ENTHALPY'} and {\ct 'SENSIBLE ENTHALPY'} are $\rho h$ and $\rho h_{\rm s}$, respectively, in units of kJ/m$^3$.


\subsection{Computer Performance}
\label{info:TIMING}

There are several useful {\ct DEVC} {\ct QUANTITY}'s that can help monitor the performance of your computer:
\begin{description}
\item[{\ct 'ACTUATED SPRINKLERS'}] Number of activated sprinklers.
\item[{\ct 'CFL MAX'}] The maximum value of the CFL (Courant-Friedrichs-Lewy) number, the primary constraint on the time step, for the mesh in which the device is located. By default, the time step is chosen so that the CFL number remains within the range of 0.8 to 1.0. If you want to see the CFL number in each grid cell, use a slice ({\ct SLCF}) file with {\ct QUANTITY='CFL'} and {\ct CELL\_CENTERED=.TRUE.}.
\item[{\ct 'CPU TIME'}] Elapsed CPU time since the start of the simulation, in seconds.
\item[{\ct 'ITERATION'}] Number of time steps completed at the given time of the simulation.
\item[{\ct 'NUMBER OF PARTICLES'}] Number of Lagrangian particles for the {\ct MESH} in which the {\ct DEVC} is located.
\item[{\ct 'TIME STEP'}] Duration of a simulation time step, $\delta t$, in seconds.
\item[{\ct 'VN MAX'}] The maximum value of the VN (Von Neumann) number, a secondary constraint on the time step, for the mesh in which the device is located. By default, the time step is chosen so that the VN number remains below 1. If you want to see the VN number in each grid cell, use a slice ({\ct SLCF}) file with {\ct QUANTITY='VN'} and {\ct CELL\_CENTERED=.TRUE.}.
\item[{\ct 'WALL CLOCK TIME'}] Elapsed wall clock time since the start of the simulation, in seconds.
\item[{\ct 'WALL CLOCK TIME ITERATIONS'}] Elapsed wall clock time since the start of the time stepping loop, in seconds.
\end{description}
In addition, the following flags can be useful in monitoring the performance of an MPI calculation. They are typically used for debugging.
\begin{description}
\item[{\ct VELOCITY\_ERROR\_FILE}] If set to {\ct .TRUE.} on the {\ct DUMP} line, this parameter will cause FDS to create a file with a time history of the maximum error associated with the normal component of velocity at solid or interpolated boundaries.
\item[{\ct MPI\_TIMEOUT}] The amount of time, in seconds, to wait for messages sent via MPI (Message Passing Interface) before timing out. This parameter is set on the {\ct MISC} line. The default value is 10~s. This parameter is only useful in forcing a job with deadlocked messages to finish and print out information about the lost message. It is very unlikely to solve a deadlock problem.
\end{description}


\subsection{Output File Precision}
\label{info:SIG_FIGS}

There are several different output files that have the format of a comma-separated value (.csv) file. These files consist of real numbers in columns separated by commas. By default, the real numbers are formatted
\begin{lstlisting}
-1.2345678E+123
\end{lstlisting}
To change the precision of the numbers, use {\ct SIG\_FIGS} on the {\ct DUMP} line to indicate the number of significant figures in the mantissa (default is 8). Use {\ct SIG\_FIGS\_EXP} to change the number of digits in the exponent (default is 3). Keep in mind that the precision of real numbers used internally in an FDS calculation is approximately 12, equivalent to 8 byte or double precision following conventional Fortran rules.


\subsection{\emph{A Posteriori} Mesh Quality Metrics}
\label{info:meshquality}

The quality of a particular simulation is most directly tied to grid resolution.  Three output quantities are discussed here for measuring errors in the velocity and scalar fields.  It should be noted that the link between these metrics and true simulation quality is still in the research phase.  In other words, a good quality score is not sufficient to assure a good simulation (at the present time).

\subsubsection{Measure of Turbulence Resolution}

A scalar quantity referred to as the \emph{measure of turbulence resolution} \cite{Pope:2004} is defined locally as:
\begin{eqnarray}
M(\mathbf{x}) = \frac{\left\langle k_{\rm sgs} \right\rangle}{\left\langle \mbox{TKE} \right\rangle + \left\langle k_{\rm sgs} \right\rangle}
\end{eqnarray}
where the resolved turbulent kinetic energy per unit mass is:
\vskip-.6cm
\begin{align}
\mbox{TKE} &= \mbox{$\frac{1}{2}$}(\textbf{u}_i - \left\langle \textbf{u}_i \right\rangle) (\textbf{u}_i - \left\langle \textbf{u}_i \right\rangle)
\end{align}
Where $\textbf{u}$ is the cell centered velocity vector from the velocity components at cell faces (i.e. $ \tilde{\textbf{u}}=\left( \bar{u},\bar{v},\bar{w} \right) $), angled brackets denote time-averaged values and subscript $i$ indicate grid indices. To output resolved TKE use the following {\ct DEVC}s to output the three velocity components:

\begin{lstlisting}
&DEVC ..., QUANTITY='U-VELOCITY' /
&DEVC ..., QUANTITY='V-VELOCITY' /
&DEVC ..., QUANTITY='W-VELOCITY' /
\end{lstlisting}

The output of these {\ct DEVC}s must be post-processed to obtain resolved TKE. First, output the velocity vector $\textbf{u}$ using the velocity components, choose a suitable time-averaging period (which will be case-specific), output a mean velocity $\left\langle \textbf{u} \right\rangle$ and hence the fluctuation in velocity $(\textbf{u} - \left\langle \textbf{u} \right\rangle)$.

The subgrid kinetic energy is estimated from Deardorff's eddy viscosity model
\begin{align}
k_{\rm sgs} &\approx \mbox{$\frac{1}{2}$}(\tilde{u}_i - \hat{\tilde{u}}_i)(\tilde{u}_i - \hat{\tilde{u}}_i) = ( \mu_t/(\rho C_\nu \Delta) )^2
\end{align}
Here, $C_\nu$ is the Deardorff eddy viscosity model constant, $\tilde{u}_i$ is the resolved LES velocity and $\hat{\tilde{u}}_i$ is test filtered at a scale $2\Delta$ where $\Delta$ is the LES filter width (in FDS, $\Delta=\delta x$).  In the bulk flow region, the model for the SGS fluctuations is taken from scale similarity \cite{Bardina:1980}.  Cross-term energy is ignored.  Keep in the mind, however, that the test filter operation is ill-defined near walls, and so FDS employs constant Smagorinsky in these cells to compute the eddy viscosity.

To output an estimate of the subgrid kinetic energy per unit mass use
\begin{lstlisting}
&DEVC ..., QUANTITY='SUBGRID KINETIC ENERGY' /
\end{lstlisting}

The concept behind the measure of turbulence resolution is illustrated in Figure \ref{fig_mtr}. Notice that on the left the difference between the grid signal and the test signal is very small.  On the right, the grid signal is highly turbulent and the corresponding test signal is much smoother.  We infer then that the flow is under-resolved.
\begin{figure}[ht]
\centering
\begin{tabular}{rl}
\includegraphics[width=3.2in]{FIGURES/mtr_resolved_signal} &
\includegraphics[width=3.2in]{FIGURES/mtr_unresolved_signal}
\end{tabular}
\vskip-0.2cm
\caption[Examples of the measure of turbulence resolution]{(Left) Resolved signal, $M$ is small. (Right) Unresolved signal, $M$ is close to unity.}
\label{fig_mtr}
\end{figure}

For the canonical case of isotropic turbulence Pope actually defines LES such that $M<0.2$.  That is, LES requires resolution of 80\% of the kinetic energy in the flow field (because this puts the grid Nyquist limit within the inertial subrange).  The question remains as to whether this critical value is sufficient or necessary for a given engineering problem.  As shown in Ref.~\cite{McDermott:2010}, maintaining mean values of $M$ near 0.2 indeed provides satisfactory results (simulation results within experimental error bounds) for mean velocities and species concentrations in non-reacting, buoyant plumes.


\subsubsection{Wavelet Error Measure}
\label{wavelets}

A resolution metric that we call the \emph{wavelet error measure} or WEM may be output using, for example,

\begin{lstlisting}
&SLCF PBY=0, QUANTITY='WAVELET ERROR', QUANTITY2='HRRPUV' /
\end{lstlisting}

We begin by providing background on the simple Haar wavelet \cite{Nievergelt:1999}.  For a thorough and more sophisticated review of wavelet methods, the reader is referred to Schneider and Vasilyev \cite{Schneider:2010}.

Suppose the scalar function $f(r)$ is sampled at discrete points $r_j$, separated by a distance $h$, giving values $s_j$.  Defining the \emph{unit step function} over the interval $[r_1,r_2]$ by
\begin{eqnarray}
\varphi_{[r_1,r_2]} = \left\{ \begin{array}{ll} 1 & \quad \mbox{if} \quad r_1 \le r < r_2 \\ 0 & \quad \mbox{otherwise} \end{array} \right.
\end{eqnarray}
the simplest possible reconstruction of the signal is the step function approximation
\begin{eqnarray}
f(r) \approx \sum_j s_j \varphi_{[r_j,r_j+h]}(r)
\end{eqnarray}
By ``viewing'' the signal at a coarser resolution, say $2h$, an identical reconstruction of the function $f$ over the interval $[r_j,r_j+2h]$ may be obtained from
\begin{eqnarray}
\label{eqn_wavelet_decomp}
f_{[r_j,r_j+2h]}(r) = \underbrace{\frac{s_j+s_{j+1}}{2}}_a \,\varphi_{[r_j,r_j+2h]}(r) + \underbrace{\frac{s_j-s_{j+1}}{2}}_c \,\psi_{[r_j,r_j+2h]}(r)
\end{eqnarray}
where $a$ is as the \emph{average} coefficient and $c$ is as the \emph{wavelet} coefficient.  The Haar \emph{mother wavelet} (Figure \ref{fig_haar_mother}) is identified as
\begin{eqnarray}
\psi_{[r_1,r_2]}(r) = \left\{ \begin{array}{ll} 1 & \quad \mbox{if} \quad r_1\le r < \frac{1}{2}(r_1+r_2) \\ -1 & \quad \mbox{if} \quad \frac{1}{2}(r_1+r_2)\le r < r_2 \end{array} \right.
\end{eqnarray}

\begin{figure}[ht]
\centering
\includegraphics[width=3.2in]{FIGURES/haar_mother}
\vskip-0.2cm
\caption[Haar mother wavelet]{Haar mother wavelet on the interval [0,1].}
\label{fig_haar_mother}
\end{figure}

The decomposition of the signal shown in Eq.~(\ref{eqn_wavelet_decomp}) may be repeated at ever coarser resolutions.  The result is a \emph{wavelet transform}. The procedure is entirely analogous to the Fourier transform, but with compact support.  If we look at a 1D signal with $2^m$ points, the repeated application of (\ref{eqn_wavelet_decomp}) results in an $m \times m$ matrix of averages $\mathbf{a}$ with components $a_{ij}$ and an $m \times m$ wavelet coefficient matrix $\mathbf{c}$ with components $c_{ij}$.  Each row $i$ of $\mathbf{a}$ may be reconstructed from the $i+1$ row of $\mathbf{a}$ and $\mathbf{c}$.  Because of this and because small values of the wavelet coefficient matrix may be discarded, dramatic compression of the signal may be obtained.

Here we are interested in using the wavelet analysis to say something about the local level of error due to grid resolution.  Very simply, we ask what can be discerned from a sample of four data points along a line.  Roughly speaking we might expect to see one of the four scenarios depicted in Figure \ref{fig_wavelet_transforms}.  Within each plot window we also show the results of a Haar wavelet transform for that signal.  Looking first at the two top plots, on the left we have a step function and on the right we have a straight line.  Intuitively, we expect large error for the step function and small error for the line.  The following error measure achieves this goal:
\begin{eqnarray}
\mbox{WEM}(\mathbf{x},t) = \max_{x,y,z}\left( \frac{|c_{11} + c_{12}| - |c_{21}|}{|a_{21}|} \right)
\end{eqnarray}
Note that we have arbitrarily scaled the measure so that a step function leads to WEM of unity.  In practice the transform is performed in all coordinate directions and the max value is reported.  The scalar value may be output to Smokeview at the desired time interval.
\begin{figure}[ht]
\centering
\begin{tabular}{rl}
\includegraphics[width=3.2in]{FIGURES/haar_step} &
\includegraphics[width=3.2in]{FIGURES/haar_line} \\
\includegraphics[width=3.2in]{FIGURES/haar_eddy} &
\includegraphics[width=3.2in]{FIGURES/haar_extr}
\end{tabular}
\vskip-0.2cm
\caption[Haar wavelet transforms on four typical signals]{Averages and coefficients for local Haar wavelet transforms on four typical signals.}
\label{fig_wavelet_transforms}
\end{figure}

Looking now at the two plots on the bottom of Figure \ref{fig_wavelet_transforms}, the signal on the left, which may indicate spurious oscillations or unresolved turbulent motion, leads to $\mbox{WEM} = 2$.  Our measure therefore views this situation as the worst case in a sense.  The signal to the lower right is indicative of an extremum, which actually is easily resolved by most centered spatial schemes and results again in $\mbox{WEM}=0$.

In \cite{McDermott:2010}, the time average of WEM was reported for LES of a non-reacting buoyant plume at three grid resolutions.  From this study, the best advice currently is to maintain average values of WEM less than 0.5.

\subsubsection{Local Cell Reynolds Number}

Additionally, we provide an estimate of the \emph{local cell Reynolds number} given by the ratio of the cell size (LES filter width, $\Delta$) to an estimate of the local Kolmogorov scale, $\eta$ (see \cite{Pope:2000}).  For a DNS, $\Delta/\eta$ should be less than or equal to one. The Kolmogorov scale is computed from its definition:
\begin{equation}
\eta \equiv \left(\frac{(\mu/\rho)^3}{\varepsilon}\right)^{1/4}
\end{equation}
where $\mu$ is the molecular dynamic viscosity, $\rho$ is the density, and $\varepsilon$ is the kinetic energy dissipation rate, which requires modeling.  In FDS, we assume the dissipation rate is locally equivalent to the production of subgrid-scale kinetic energy.  This implies
\begin{equation}
\varepsilon = (\mu_t/\rho)|\tilde{S}|^2
\end{equation}
where $\mu_t$ is the turbulent viscosity and $|\tilde{S}|$ is the filtered strain invariant (see FDS Tech Guide).

\begin{lstlisting}
&SLCF PBY=0, QUANTITY='CELL REYNOLDS NUMBER' /
\end{lstlisting}

\subsubsection{Near-Wall Grid Resolution}
\label{info:yplus}

Large-eddy simulations of boundary layer flows fall into two general categories: LES with near-wall resolution and LES with near-wall modeling (wall functions).  FDS employs the latter.  The wall models used in FDS are law of the wall \cite{Pope:2000}.  For the wall models to function properly, the grid resolution near the wall should fall within a certain range of $y^+$, the nondimensional distance from the wall expressed in viscous units.  To check this, you may add a boundary file output as follows:

\begin{lstlisting}
&BNDF QUANTITY='VISCOUS WALL UNITS' /
\end{lstlisting}

\noindent
The value of $y^+$ reported is half (since the velocity lives at the cell face center) the wall-normal cell dimension ($\delta n$) divided by the maximum between the local viscous length scale, $\delta_\nu$ \cite{Pope:2000} or the sand grain roughness, $s$, for rough walls:
\be
y^+ = \frac{\delta n/2}{\max(\delta_\nu,s)} \,\mbox{;} \quad\quad \delta_\nu = \frac{\mu/\rho}{u_\tau} \,\mbox{;} \quad\quad u_\tau = \sqrt{\tau_w/\rho} \,\mbox{,}
\ee
where $\tau_{\rm w} = \mu\,\partial |\mathbf{u}|/\partial n$ is the viscous stress evaluated at the wall ($\tau_{\rm w}$ is computed by the wall function, $|\mathbf{u}|$ is taken as an estimate of the streamwise velocity component near the wall); the quantity $u_\tau$ is the \emph{friction velocity}.  The friction velocity may also be output in a boundary file or via a device attached to a wall.  For example:
\begin{lstlisting}
&DEVC XYZ=1,0,0, QUANTITY='FRICTION VELOCITY', IOR=3, ID='u_tau' /
\end{lstlisting}

\noindent Wall functions for LES are still under development, but as a general guideline it is recommended that the first grid cell fall within the log layer: a value $y^+=30$ would be considered highly resolved, the upper limit of the log region for statistically stationary boundary layers depends on the Reynolds number, and there are no hard rules for transient flows.  Beyond $y^+=1000$ the first grid cell is likely to fall in the wake region of the boundary layer and may produce unreliable results.  A reasonable target for practical engineering LES is $y^+ = {\cal O}(100)$.


\subsection{Extinction}
\label{info:extinct_out}
In combustion, knowing if, when, or where chemical reactions have been extinguished is important. The output quantity {\ct EXTINCTION} tells the user whether or not combustion has been prevented by the extinction routine. By default, {\ct EXTINCTION} = 0, which means that the FDS extinction routine has not prevented combustion. An {\ct EXTINCTION} value of 1 means that the routine has prevented combustion. The criteria for an {\ct EXTINCTION} value of 1 is the presence of fuel and oxidizer without any energy release. An {\ct EXTINCTION} value of -1 means that there is either no fuel or no oxidizer present.




\section{Extracting Numbers from the Output Data Files}
\label{info:fds2ascii}

As part of the standard FDS-SMV distribution package, there is a short Fortran program called {\ct fds2ascii}\footnote{The source code is located in the GitHub repository, {\ct \footnotesize firemodels/fds}, in the directory, {\ct \footnotesize Utilities/fds2ascii}.}. To run the program, just type:
\begin{lstlisting}
fds2ascii
\end{lstlisting}
at the command prompt. You will be asked a series of questions about which type of output file to process, what time interval to time average the data, and so forth. A single file is produced with the name {\ct CHID\_fds2ascii.csv}. A typical command line session looks like this:
\begin{lstlisting}
>> fds2ascii
  Enter Job ID string (CHID):
bucket_test_1
  What type of file to parse?
  PL3D file? Enter 1
  SLCF file? Enter 2
  BNDF file? Enter 3
3
  Enter Sampling Factor for Data?
  (1 for all data, 2 for every other point, etc.)
1
  Limit the domain size? (y or n)
y
  Enter min/max x, y and z
-5 5 -5 5 0 1
  1   MESH  1, WALL TEMPERATURE
  Enter starting and ending time for averaging (s)
35 36
  Enter orientation: (plus or minus 1, 2 or 3)
3
  Enter number of variables
1
 Enter boundary file index for variable 1
1
 Enter output file name:
bucket_test_1_fds2ascii.csv
  Writing to file...      bucket_test_1_fds2ascii.csv
\end{lstlisting}
These commands tell {\ct fds2ascii} that you want to convert (binary) boundary file data into a text file. You want to sample every data point within the specified volume, you want only those surfaces that point upwards (+3 orientation), you only want 1 variable (only one is listed anyway and its index is 1 -- that is just the number used to list the available files). The data will be time-averaged, and it will be output to a file listed at the end of the session. Here is a more detailed explanation of the questions:
\begin{description}
\item[Enter Job ID string (CHID):] Enter the name of the job that you entered into the FDS input file under the parameter {\ct CHID}. Do not include the {\ct .fds} suffix.
\item[What type of file to parse?] The program can only read Plot3D ({\ct PL3D}), slice ({\ct SLCF}), or boundary ({\ct BNDF}) files.
\item[Enter Sampling Factor for Data:] If you want to print out every point, enter 1; every other point, enter 2; and so on.
\item[Domain selection:] The answer is a one or two letter code. If the first letter is {\ct y} or {\ct Y}, this means you want to print out a subset of the data for the entire domain. If {\ct n} or {\ct N}, you do not want to limit the data. The answer of {\ct z} or {\ct Z} is only for cases where you have an outdoor fire scenario over rough terrain, and you want to offset the $z$ coordinate so that it denotes height off the ground. If the second letter of the two letter code is {\ct a} or {\ct A}, this means that you want the program to \underline{a}utomatically select the appropriate files. If the first letter of the two letter code is {\ct y} or {\ct Y}, you will be prompted for 6 numbers denoting the minimum and maximum values of $x$, $y$, and $z$.
\item[Enter starting and ending time for averaging (s):] The slice and boundary file data will be time-averaged over the designated time interval.
\item[How many variables to read:] Enter the number of different output quantities that you want to include in your output file.
\item[Enter orientation: (plus or minus 1, 2 or 3):] For a boundary file, you must designate the orientation of the surfaces you want to print out. +1 means surfaces facing the positive $x$ direction, -2 means negative $y$, and so on.
\end{description}



\section{Summary of Frequently-Used Output Quantities}
\label{info:outputquantities}

Table~\ref{tab:output}, spread over the following pages, summarizes the various Output Quantities. The column ``File Type'' lists the allowed output files for the quantities. ``B'' is for Boundary ({\ct BNDF}), ``D'' is for Device ({\ct DEVC}), ``I'' is for Iso-surface ({\ct ISOF}), ``P'' is for Plot3D, ``PA'' for PArticle ({\ct PART}), ``S'' is for Slice ({\ct SLCF}). Be careful when specifying complicated quantities for Iso-surface or Plot3D files, as it requires computation in every gas phase cell.

For those output quantities that require a species name via {\ct SPEC\_ID}, the species implicitly defined when using the simple chemistry combustion model are {\ct 'OXYGEN'}, {\ct 'NITROGEN'}, {\ct 'WATER VAPOR'}, and {\ct 'CARBON DIOXIDE'}. If {\ct CO\_YIELD} and/or {\ct SOOT\_YIELD} are specified on the {\ct REAC} line, then {\ct 'CARBON MONOXIDE'} and {\ct 'SOOT'} are included as output species. The fuel species can be output via the {\ct FUEL} specified on the {\ct REAC} line. As an example of how to use the species names, suppose you want to calculate the integrated mass flux of carbon monoxide through a horizontal plane, like the total amount entrained in a fire plume. Use a ``device'' as follows
\begin{lstlisting}
&DEVC ID='CO_flow', XB=-5,5,-5,5,2,2, QUANTITY='MASS FLUX Z',
      SPEC_ID='CARBON MONOXIDE', SPATIAL_STATISTIC='AREA INTEGRAL' /
\end{lstlisting}
Here, the {\ct ID} is just a label in the output file. When an output quantity is related to a particular gas species or particle type, you must specify the appropriate {\ct SPEC\_ID} or {\ct PART\_ID} on the same input line. Also note that the use of underscores in output quantity names has been eliminated -- just remember that all output quantity names ought to be in single quotes.


\clearpage

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|}
\caption[Frequently used output quantities]{Summary of frequently used output quantities.}
\label{tab:output} \\
\hline
{\ct QUANTITY}                           & Symbol                                        & Units          & File Type    \\
\hline \hline
\endfirsthead
\caption[]{Summary of frequently used output quantities (continued).} \\
\hline
{\ct QUANTITY}                           & Symbol                                        & Units          & File Type    \\
\hline \hline
\endhead
{\ct ABSORPTION COEFFICIENT}                    & Section~\ref{info:RADI_RADCAL_Absorption}     & 1/m            & D,I,P,S      \\ \hline
{\ct ACTUATED SPRINKLERS}                       & Section~\ref{info:TIMING}                     &                & D            \\ \hline
{\ct ADIABATIC SURFACE TEMPERATURE}             & Section~\ref{info:AST}                        & $^\circ$C      & B,D          \\ \hline
{\ct AEROSOL VOLUME FRACTION}$^1$               & Section~\ref{info:soot}                       & mol/mol        & D,I,P,S      \\ \hline
{\ct AMPUA}$^2$                                 & Section~\ref{info:part_output}                & kg/m$^2$       & B,D          \\ \hline
{\ct AMPUA\_Z}$^1$                              & Section~\ref{info:part_output}                & kg/m$^2$       & B,D          \\ \hline
{\ct ASPIRATION}                                & Section~\ref{info:aspiration_detector}        & \%/m           & D            \\ \hline
{\ct BACKGROUND PRESSURE}                       & Background pressure, $\bp$                    & Pa             & D,I,P,S      \\ \hline
{\ct BACK WALL TEMPERATURE}                     & Section~\ref{info:BACK}                       & $^\circ$C      & B,D          \\ \hline
{\ct BURNING RATE}                              & Mass loss rate of fuel                        & \si{kg/(m$^2$.s)} & B,D       \\ \hline
{\ct CHAMBER OBSCURATION}                       & Section~\ref{info:smoke_detector}             & \%/m           & D            \\ \hline
{\ct CHI\_R}                                    & Section~\ref{info:CHI_R}             &                & D,I,S        \\ \hline
{\ct CONDUCTIVITY}                              & Thermal conductivity                          & \si{W/(m.K)}   & D,I,P,S      \\ \hline
{\ct CONTROL}                                   & Section~\ref{info:CTRL}                       &                & D            \\ \hline
{\ct CONTROL VALUE}                             & Section~\ref{info:CTRL}                       &                & D            \\ \hline
{\ct CONVECTIVE HEAT FLUX}                      & Section~\ref{info:heat_flux}                  & kW/m$^2$       & B,D          \\ \hline
{\ct CPUA}$^2$                                  & Section~\ref{info:part_output}                & kW/m$^2$       & B,D          \\ \hline
{\ct CPUA\_Z}$^1$                               & Section~\ref{info:part_output}                & kW/m$^2$       & B,D          \\ \hline
{\ct CPU TIME}                                  & Section~\ref{info:TIMING}                     & s              & D            \\ \hline
{\ct DENSITY}                                   & $\rho$ or $\rho Y_\alpha$ with {\ct SPEC\_ID} & kg/m$^3$       & D,I,P,S      \\ \hline
{\ct DEPOSITION VELOCITY}                       & Section~\ref{info:deposition}                 & m/s            & B,D          \\ \hline
{\ct DIVERGENCE}                                & $\nabla \cdot \bu$                            & 1/s            & D,I,P,S      \\ \hline
{\ct ENTHALPY}                                  & Section~\ref{info:Enthalpy}                   & kJ/m$^3$       & D,I,P,S      \\ \hline
{\ct EXTINCTION COEFFICIENT}                    & Section~\ref{info:visibility}                 & 1/m            & D,I,P,S      \\ \hline
{\ct FED}                                       & Section~\ref{info:FED}                        &                & D            \\ \hline
{\ct FIC}                                       & Section~\ref{info:FED}                        &                & D,S          \\ \hline
{\ct FRICTION VELOCITY}                         & Section~\ref{info:yplus}                      & m/s            & B,D          \\ \hline
{\ct GAUGE HEAT FLUX}                           & Section~\ref{info:heat_flux}                  & kW/m$^2$       & B,D          \\ \hline
{\ct HEAT FLOW}                                 & Section~\ref{info:flows}                      & kW             & D            \\ \hline
{\ct HEAT FLOW WALL}                            & Section~\ref{info:flows}                      & kW             & D            \\ \hline
{\ct NET HEAT FLUX}                             & Section~\ref{info:heat_flux}                  & kW/m$^2$       & B,D          \\ \hline
{\ct HRR}                                       & $\int \dq''' \; \d V$                         & kW             & D            \\ \hline
{\ct HRRPUA}                                    & $\dq''$                                       & kW/m$^2$       & D            \\ \hline
{\ct HRRPUV}                                    & $\dq'''$                                      & kW/m$^3$       & D,I,P,S      \\ \hline
{\ct INCIDENT HEAT FLUX}                        & Section~\ref{info:heat_flux}                  & kW/m$^2$       & B,D          \\ \hline
{\ct INSIDE WALL TEMPERATURE}                   & Section~\ref{info:DEPTH}                      & $^\circ$C      & D            \\ \hline
{\ct INSIDE WALL DEPTH}                         & Section~\ref{info:DEPTH}                      & m              & D            \\ \hline
{\ct ITERATION}                                 & Section~\ref{info:TIMING}                     &                & D            \\ \hline
{\ct LAYER HEIGHT}                              & Section~\ref{info:layerheight}                & m              & D            \\ \hline
{\ct LINK TEMPERATURE}                          & Section~\ref{info:heat_detectors}             & $^\circ$C      & D            \\ \hline
{\ct LOWER TEMPERATURE}                         & Section~\ref{info:layerheight}                & $^\circ$C      & D            \\ \hline
{\ct MASS FLOW}                                 & Section~\ref{info:flows}                      & kg/s           & D            \\ \hline
{\ct MASS FLOW WALL}                            & Section~\ref{info:flows}                      & kg/s           & D            \\ \hline
{\ct MASS FLUX}$^1$                             & Section~\ref{info:wallflux}                   & \si{kg/(m$^2$.s)} & B,D       \\ \hline
{\ct MASS FLUX WALL}$^1$                        & Section~\ref{info:wallflux}                   & \si{kg/(m$^2$.s)} & B,D       \\ \hline
{\ct MASS FLUX X}$^1$                           & $\rho u Y_\alpha$                             & \si{kg/(m$^2$.s)} & D,I,P,S   \\ \hline
{\ct MASS FLUX Y}$^1$                           & $\rho v Y_\alpha$                             & \si{kg/(m$^2$.s)} & D,I,P,S   \\ \hline
{\ct MASS FLUX Z}$^1$                           & $\rho w Y_\alpha$                             & \si{kg/(m$^2$.s)} & D,I,P,S   \\ \hline
{\ct MASS FRACTION}$^1$                         & $Y_\alpha$                                    & kg/kg          & D,I,P,S      \\ \hline
{\ct MIXTURE FRACTION}                          & $Z$                                           & kg/kg          & D,I,P,S      \\ \hline
{\ct MPUA}$^2$                                  & Section~\ref{info:part_output}                & kg/m$^2$       & B,D          \\ \hline
{\ct MPUA\_Z}$^1$                               & Section~\ref{info:part_output}                & kg/m$^2$       & B,D          \\ \hline
{\ct MPUV}$^2$                                  & Section~\ref{info:part_output}                & kg/m$^3$       & D,P,S        \\ \hline
{\ct MPUV\_Z}$^1$                               & Section~\ref{info:part_output}                & kg/m$^3$       & D,P,S        \\ \hline
{\ct NORMAL VELOCITY}                           & Wall normal velocity                          & m/s            & D,B          \\ \hline
{\ct NUMBER OF PARTICLES}                       & Section~\ref{info:TIMING}                     &                & D            \\ \hline
{\ct OPEN NOZZLES}                              & Section~\ref{info:TIMING}                     &                & D            \\ \hline
{\ct OPTICAL DENSITY}                           & Section~\ref{info:visibility}                 & 1/m            & D,I,P,S      \\ \hline
{\ct PATH OBSCURATION}                          & Section~\ref{info:beam_detector}              & \%             & D            \\ \hline
{\ct PARTICLE AGE}                              & Section~\ref{info:part_output}                & s              & PA           \\ \hline
{\ct PARTICLE DIAMETER}                         & Section~\ref{info:part_output}                & $\mu$m         & PA           \\ \hline
{\ct PARTICLE FLUX X}$^2$                       & Section~\ref{info:part_output}                & \si{kg/(m$^2$.s)} & P,S       \\ \hline
{\ct PARTICLE FLUX Y}$^2$                       & Section~\ref{info:part_output}                & \si{kg/(m$^2$.s)} & P,S       \\ \hline
{\ct PARTICLE FLUX Z}$^2$                       & Section~\ref{info:part_output}                & \si{kg/(m$^2$.s)} & P,S       \\ \hline
{\ct PARTICLE MASS}                             & Section~\ref{info:part_output}                & kg             & PA           \\ \hline
{\ct PARTICLE TEMPERATURE}                      & Section~\ref{info:part_output}                & $^\circ$C      & PA           \\ \hline
{\ct PARTICLE VELOCITY}                         & Section~\ref{info:part_output}                & m/s            & PA           \\ \hline
{\ct PRESSURE}                                  & Perturbation pressure, $\tp-p_\infty$         & Pa             & D,I,P,S      \\ \hline
{\ct PRESSURE COEFFICIENT}                      & Section~\ref{info:pressure_coefficient}       &                & B,D          \\ \hline
{\ct PRESSURE ZONE}                             & Section~\ref{info:ZONE}                       &                & D,S          \\ \hline
{\ct RADIATIVE HEAT FLUX}                       & Section~\ref{info:heat_flux}                  & kW/m$^2$       & B,D          \\ \hline
{\ct RADIATIVE HEAT FLUX GAS}                   & Section~\ref{info:heat_flux}                  & kW/m$^2$       & D            \\ \hline
{\ct RADIOMETER}                                & Section~\ref{info:heat_flux}                  & kW/m$^2$       & B,D          \\ \hline
{\ct RELATIVE HUMIDITY}                         & Section~\ref{info:simple_chemistry}           & \%             & D,I,P,S      \\ \hline
{\ct SENSIBLE ENTHALPY}                         & Section~\ref{info:enthalpy}                   & kJ/m$^3$       & D,I,P,S      \\ \hline
{\ct SOLID CELL DENSITY}                        & Section~\ref{info:pyro3d}                     & kg/m$^3$       & D,I,P,S      \\ \hline
{\ct SOLID CELL Q\_S}                           & Section~\ref{info:pyro3d}                     & kW/m$^3$       & D,I,P,S      \\ \hline
{\ct SOLID CELL VOLUME RATIO}                   & Section~\ref{info:pyro3d}                     & m$^3$/m$^3$    & D,I,P,S      \\ \hline
{\ct SOLID CONDUCTIVITY}                        & Section~\ref{info:DEPTH}                      & \si{W/(m.K)}   & D            \\ \hline
{\ct SOLID DENSITY}                             & Section~\ref{info:DEPTH}                      & kg/m$^3$       & D            \\ \hline
{\ct SOLID SPECIFIC HEAT}                       & Section~\ref{info:DEPTH}                      & \si{kJ/(kg.K)} & D            \\ \hline
{\ct SPECIFIC ENTHALPY}                         & Section~\ref{info:enthalpy}                   & kJ/kg          & D,I,P,S      \\ \hline
{\ct SPECIFIC HEAT}                             & $c_p$                                         & \si{kJ/(kg.K)} & D,I,P,S      \\ \hline
{\ct SPECIFIC SENSIBLE ENTHALPY}                & Section~\ref{info:enthalpy}                   & kJ/kg          & D,I,P,S      \\ \hline
{\ct SPRINKLER LINK TEMPERATURE}                & Section~\ref{info:sprinklers}                 & $^\circ$C      & D            \\ \hline
{\ct SURFACE DENSITY}                           & Section~\ref{info:material_components}        & kg/m$^2$       & B,D          \\ \hline
{\ct SURFACE DEPOSITION}$^1$                    & Section~\ref{info:deposition}                 & kg/m$^2$       & B,D          \\ \hline
{\ct TEMPERATURE}                               & Section~\ref{info:THERMOCOUPLE}               & $^\circ$C      & D,I,P,S      \\ \hline
{\ct THERMOCOUPLE}                              & Section~\ref{info:THERMOCOUPLE}               & $^\circ$C      & D            \\ \hline
{\ct TIME}                                      & Section~\ref{info:DEVC}                       & s              & D            \\ \hline
{\ct TIME STEP}                                 & Section~\ref{info:TIMING}                     & s              & D            \\ \hline
{\ct TRANSMISSION}                              & Section~\ref{info:beam_detector}              & \%/m           & D            \\ \hline
{\ct U-VELOCITY}                                & Gas velocity component, $u$                   & m/s            & D,I,P,S      \\ \hline
{\ct V-VELOCITY}                                & Gas velocity component, $v$                   & m/s            & D,I,P,S      \\ \hline
{\ct W-VELOCITY}                                & Gas velocity component, $w$                   & m/s            & D,I,P,S      \\ \hline
{\ct UPPER TEMPERATURE}                         & Section~\ref{info:layerheight}                & $^\circ$C      & D            \\ \hline
{\ct VELOCITY}$^3$                              & Gas velocity                                  & m/s            & D,I,P,S      \\ \hline
{\ct VISCOSITY}                                 & Effective viscosity, $\mu + \mu_{\mathrm{t}}$ & \si{kg/(m.s)}  & D,I,P,S      \\ \hline
{\ct VISIBILITY}                                & Section~\ref{info:visibility}                 & m              & D,I,P,S      \\ \hline
{\ct VOLUME FLOW}                               & Section~\ref{info:flows}                      & m$^3$/s        & D            \\ \hline
{\ct VOLUME FLOW WALL}                          & Section~\ref{info:flows}                      & m$^3$/s        & D            \\ \hline
{\ct VOLUME FRACTION}$^1$                       & $X_\alpha$                                    & mol/mol        & D,I,P,S      \\ \hline
{\ct WALL CLOCK TIME}                           & Section~\ref{info:TIMING}                     & s              & D            \\ \hline
{\ct WALL CLOCK TIME ITERATIONS}                & Section~\ref{info:TIMING}                     & s              & D            \\ \hline
{\ct WALL TEMPERATURE}                          & Surface temperature                           & $^\circ$C      & B,D          \\ \hline
{\ct WALL THICKNESS}                            & Section~\ref{info:material_components}        & m              & B,D          \\ \hline
\end{longtable}

\noindent
\begin{tabbing}
$^1$  \hspace{0.05in} \= Requires the specification of a gas species using {\ct SPEC\_ID}. \\
                      \> Omit {\ct SPEC\_ID} for total flux. \\
                      \> Do not use for {\ct MIXTURE FRACTION}. \\
$^2$                  \> Requires the specification of a particle name using {\ct PART\_ID}. \\
$^3$                  \> Add {\ct VELO\_INDEX=1} to the input line if you want to multiply the velocity by the sign of $u$. \\
                      \> Use the indices 2 and 3 for $v$ and $w$, respectively.\\
$^4$                  \> Allows for an optional {\ct MATL\_ID}.

\end{tabbing}

\clearpage

\section{Summary of Infrequently-Used Output Quantities}
\label{info:oddoutputquantities}

Table~\ref{tab:oddoutput} below lists some less often used output quantities. These are mainly used for diagnostic purposes. Explanations for most can
be found in Volume~1 of the FDS Technical Reference Guide~\cite{FDS_Math_Guide}.

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|}
\caption[Infrequently used output quantities]{Summary of {\em infrequently} used output quantities.}
\label{tab:oddoutput} \\
\hline
{\ct QUANTITY}                           & Symbol                                        & Units          & File Type    \\
\hline \hline
\endfirsthead
\caption[]{Summary of {\em infrequently} used output quantities (continued).} \\
\hline
{\ct QUANTITY}                           & Symbol                                        & Units          & File Type    \\
\hline \hline
\endhead
{\ct ABSOLUTE PRESSURE}                         & Absolute Pressure                                 & Pa             & D,I,P,S      \\ \hline
{\ct ADA}$^2$                                   & Avg.~Droplet (cross sectional) Area               & m$^2$/m$^3$    & D,I,P,S      \\ \hline
{\ct ADA\_Z}$^1$                                & Avg.~Droplet (cross sectional) Area               & m$^2$/m$^3$    & D,I,P,S      \\ \hline
{\ct ADD}$^2$                                   & Avg.~Droplet Diameter                             & $\mu$m         & D,I,P,S      \\ \hline
{\ct ADD\_Z}$^1$                                & Avg.~Droplet Diameter                             & $\mu$m         & D,I,P,S      \\ \hline
{\ct ADT}$^2$                                   & Avg.~Droplet Temperature                          & $^\circ$C      & D,I,P,S      \\ \hline
{\ct ADT\_Z}$^1$                                & Avg.~Droplet Temperature                          & $^\circ$C      & D,I,P,S      \\ \hline
{\ct ASSUMED GAS TEMPERATURE}                   & Section~\ref{solid_phase_verification}            & $^\circ$C      & D,I,P,S      \\ \hline
{\ct C\_SMAG}                                   & Smagorinsky coefficient                           &                & D,I,P,S      \\ \hline
{\ct AUTO IGNITION TEMPERATURE}$^5$             & Section \ref{info:ignition}                       & $^\circ$C      & D,I,P,S      \\ \hline
{\ct CABLE TEMPERATURE}                         & Inner temperature of cable                        & $^\circ$C      & D            \\ \hline
{\ct CELL INDEX I}                              & Mesh cell index in x                              &                & D,S          \\ \hline
{\ct CELL INDEX J}                              & Mesh cell index in y                              &                & D,S          \\ \hline
{\ct CELL INDEX K}                              & Mesh cell index in z                              &                & D,S          \\ \hline
{\ct CELL REYNOLDS NUMBER}                      & Section \ref{info:meshquality}                    &                & D,I,P,S      \\ \hline
{\ct CELL U}                                    & $(u_{i,j,k}+u_{i-1,j,k})/2$                       & m/s            & D,I,P,S      \\ \hline
{\ct CELL V}                                    & $(v_{i,j,k}+v_{i,j-1,k})/2$                       & m/s            & D,I,P,S      \\ \hline
{\ct CELL W}                                    & $(w_{i,j,k}+w_{i,j,k-1})/2$                       & m/s            & D,I,P,S      \\ \hline
{\ct CFL}                                       & Section~\ref{info:TIMING}                         &                & D,I,P,S      \\ \hline
{\ct CFL MAX}                                   & Section~\ref{info:TIMING}                         &                & D            \\ \hline
{\ct CHEMISTRY SUBITERATIONS}                   & Section~\ref{info:chem_integration}               &                & D,S          \\ \hline
{\ct COMBUSTION EFFICIENCY}                     & $\min(\delta t/\tau_{\mathrm{mix}},1)$, if $\dq'''>0$, else 0 &    & D,I,P,S      \\ \hline
{\ct DIFFUSIVITY}$^1$                           & Species diffusivity                               & m$^2$/s        & D,I,P,S      \\ \hline
{\ct DISSIPATION RATE}                          & $\mu / \rho \times $ {\ct STRAIN RATE}            & m$^2$/s$^3$    & D,I,P,S      \\ \hline
{\ct EMISSIVITY}                                & Surface emissivity (usually constant)             &                & B,D          \\ \hline
{\ct EXTINCTION}                                & Section~\ref{info:extinct_out}                    &                & D,S          \\ \hline
{\ct F\_X, F\_Y, F\_Z}                          & Momentum terms, $F_x$, $F_y$, $F_z$               & m/s$^2$        & D,I,P,S      \\ \hline
{\ct GAS DENSITY}                               & Gas Density near wall                             & \si{kg/m^3}    & B,D          \\ \hline
{\ct GAS TEMPERATURE}                           & Gas Temperature near wall                         & $^\circ$C      & B,D          \\ \hline
{\ct H}                                         & $\cH=|\bu|^2/2 + \tp/\rho    $                    & (m/s)$^2$      & D,I,P,S      \\ \hline
{\ct HEAT TRANSFER COEFFICIENT}                 & Convective heat transfer                          & \si{W/(m^2.K)} & B,D          \\ \hline
{\ct HRRPUL}                                    & $\int \dq''' \, \d x \, \d y$                     & kW/m           & D            \\ \hline
{\ct IDEAL GAS PRESSURE}                        & $\bar{p}=\rho R T / \overline{W}$                 & Pa             & D,I,P,S      \\ \hline
{\ct INTEGRATED INTENSITY}                      & $U=\int I \, \d \bs$                              & kW/m$^2$       & D,I,P,S      \\ \hline
{\ct KINETIC ENERGY}                            & $(u^2+v^2+w^2)/2$                                 & (m/s)$^2$      & D,I,P,S      \\ \hline
{\ct KOLMOGOROV LENGTH SCALE}                   & Section \ref{info:meshquality}                    & m              & D,I,P,S      \\ \hline
{\ct MACH NUMBER}                               & $|\bu|/\sqrt{(R/\overline{W}) T \gamma}$          &                & S,D          \\ \hline
{\ct MAXIMUM VELOCITY ERROR}                    & Section \ref{info:PRES}                           & m/s            & D            \\ \hline
{\ct MIXING TIME}                               & Combustion mixing time                            & s              & D,I,P,S      \\ \hline
{\ct MOLECULAR VISCOSITY}                       & Molecular viscosity, $\mu(\mathbf{Z},T)$          & \si{kg/(m.s)}  & D,I,P,S      \\ \hline
{\ct NORMALIZED HEATING RATE}                   & Section~\ref{info:material_components}            & W/g            & D            \\ \hline
{\ct NORMALIZED HEAT RELEASE RATE}              & Section~\ref{info:material_components}            & W/g            & D            \\ \hline
{\ct NORMALIZED MASS}$^4$                       & Section~\ref{info:material_components}            &                & D            \\ \hline
{\ct NORMALIZED MASS LOSS RATE}$^4$             & Section~\ref{info:material_components}            & 1/s            & D            \\ \hline
{\ct PARTICLE PHASE}                            & Orientation of droplet                            &                & PA           \\ \hline
{\ct PARTICLE RADIATION LOSS}                   & $\nabla \cdot \bq_r''$ due to Lagrangian particles& kW/m$^3$       & D,I,P,S      \\ \hline
{\ct PDPA}                                      & Droplet diagnostics                               &                & D            \\ \hline
{\ct PRESSURE ITERATIONS}                       & Number of pressure iterations                     &                & D            \\ \hline
{\ct Q CRITERION} & $\frac{1}{2} [\mathrm{trace}(\nabla \mathbf{u})^2 - \mathrm{trace}( (\nabla \mathbf{u})^2)]$ & 1/s$^2$ & D,I,P,S \\ \hline
{\ct QABS}$^2$                                  & Absorption efficiency of droplets                 &                & D,I,P,S      \\ \hline
{\ct QABS\_Z}$^1$                               & Absorption efficiency of droplets                 &                & D,I,P,S      \\ \hline
{\ct QSCA}$^2$                                  & Scattering efficiency of droplets                 &                & D,I,P,S      \\ \hline
{\ct QSCA\_Z}$^1$                               & Scattering efficiency of droplets                 &                & D,I,P,S      \\ \hline
{\ct RADIAL VELOCITY}                           & $(u,v)\cdot(x,y)/\sqrt{x^2+y^2}$                  & m/s            & D,I,P,S      \\ \hline
{\ct RADIATION LOSS}                            & $\nabla \cdot \bq_r''$                            & kW/m$^3$       & D,I,P,S      \\ \hline
{\ct RANDOM NUMBER}                             & Uniform random variable over [0,1]                &                & D            \\ \hline
{\ct STRAIN RATE}                               & $2(S_{ij}S_{ij}-1/3(\nabla\cdot\mathbf{u})^2)$    & 1/s            & D,I,P,S      \\ \hline
{\ct STRAIN RATE X}                             & $\partial w/\partial y + \partial v/\partial z$   & 1/s            & D,I,P,S      \\ \hline
{\ct STRAIN RATE Y}                             & $\partial u/\partial z + \partial w/\partial x$   & 1/s            & D,I,P,S      \\ \hline
{\ct STRAIN RATE Z}                             & $\partial v/\partial x + \partial u/\partial y$   & 1/s            & D,I,P,S      \\ \hline
{\ct SUBGRID KINETIC ENERGY}                    & Section~\ref{info:meshquality}                    & \si{m^2/s^2}   & D,S          \\ \hline
{\ct SUM LUMPED MASS FRACTIONS}                 & $\sum_i Z_i$ (should be 1)                        &                & D,S          \\ \hline
{\ct SUM PRIMITIVE MASS FRACTIONS}              & $\sum_\alpha Y_\alpha$ (should be 1)              &                & D,S          \\ \hline
{\ct VELOCITY ERROR}                            & Section~\ref{info:PRES}                           &                & B            \\ \hline
{\ct VISCOUS WALL UNITS}                        & Section~\ref{info:yplus}                          &                & B,D          \\ \hline
{\ct VN}                                        & Section~\ref{info:TIMING}                         &                & D,I,P,S      \\ \hline
{\ct VN MAX}                                    & Section~\ref{info:TIMING}                         &                & D            \\ \hline
{\ct VORTICITY X}                               & $\partial w/\partial y - \partial v/\partial z$   & 1/s            & D,I,P,S      \\ \hline
{\ct VORTICITY Y}                               & $\partial u/\partial z - \partial w/\partial x$   & 1/s            & D,I,P,S      \\ \hline
{\ct VORTICITY Z}                               & $\partial v/\partial x - \partial u/\partial y$   & 1/s            & D,I,P,S      \\ \hline
%{\ct WALL CELL BOUNDARY TYPE}                   & Index of {\ct WC\%BOUNDARY\_TYPE} for debug       &                & B            \\ \hline
%{\ct WALL CELL THERMAL BOUNDARY TYPE}           & Index of {\ct SF\%THERMAL\_BC\_INDEX} for debug   &                & B            \\ \hline
{\ct WALL VISCOSITY}                            & Near-wall viscosity, $\mu_w$                      & \si{kg/(m.s)}  & B,D          \\ \hline
{\ct WAVELET ERROR}$^3$                         & Section~\ref{info:meshquality}                    &                & S            \\ \hline
\end{longtable}

\noindent
\begin{tabbing}
$^1$ \hspace{0.05in} \= Requires the specification of a gas species using {\ct SPEC\_ID}. Omit {\ct SPEC\_ID} for total flux. \\
$^2$                 \> Requires the specification of a particle name using {\ct PART\_ID}. \\
$^3$                 \> Requires specification of an additional scalar using {\ct QUANTITY2}. \\
$^4$                 \> Allows for an optional {\ct MATL\_ID}. \\
$^5$                 \> Allows for an optional {\ct REAC\_ID}.  Default is Reaction 1.
\end{tabbing}


\clearpage

\section{Summary of HVAC Output Quantities}
\label{info:hvacoutputquantities}

Table~\ref{tab:hvacoutput} summarizes the various Output Quantities for HVAC systems.  Quantities for a duct require the specification
of a {\ct DUCT\_ID}, and quantities for a node require the specification of a {\ct NODE\_ID}.  Mass and volume fraction outputs also require the specification of a {\ct SPEC\_ID}.

\begin{longtable}{|l|l|l|@{\extracolsep{\fill}}}
\caption[HVAC output quantities]{Summary of HVAC output quantities.}
\label{tab:hvacoutput} \\
\hline
{\ct QUANTITY}                                  & Symbol                                    & Units           \\
\hline \hline
\endfirsthead
\caption[]{Summary of HVAC output quantities (continued).} \\
\hline
{\ct QUANTITY}                                  & Symbol                                    & Units           \\
\hline \hline
\endhead
{\ct AIRCOIL HEAT EXCHANGE}                     & Heat exchange rate for an aircoil         &  kW                   \\ \hline
{\ct DUCT DENSITY}                              & Density of the flow in a duct             &  kg/m$^3$             \\ \hline
{\ct DUCT MASS FLOW}                            & Mass flow in a duct                       &  kg/s                 \\ \hline
{\ct DUCT MASS FRACTION}                        & Mass fraction of a species in a duct      &  kg/kg                \\ \hline
{\ct DUCT TEMPERATURE}                          & Temperature of the flow in a duct         & $^\circ$C             \\ \hline
{\ct DUCT VELOCITY}                             & Velocity of a duct                        &  m/s                  \\ \hline
{\ct DUCT VOLUME FLOW}                          & Volumetric flow in a duct                 &  m$^3$/s              \\ \hline
{\ct DUCT VOLUME FRACTION}                      & Volume fraction of a species in a duct    &  mol/mol              \\ \hline
{\ct FAN PRESSURE}                              & Pressure output of a fan in a duct        &  Pa                   \\ \hline
{\ct FILTER LOADING}                            & Loading of a species in a filter          &  kg                   \\ \hline
{\ct FILTER LOSS}                               & Flow loss through a filter                &                       \\ \hline
{\ct NODE DENSITY}                              & Density of the flow through a node        &  kg/m$^3$             \\ \hline
{\ct NODE MASS FRACTION}                        & Mass fraction of a species in a node      &  kg/kg                \\ \hline
{\ct NODE PRESSURE}                             & Pressure of a node                        &       Pa              \\ \hline
{\ct NODE PRESSURE DIFFERENCE}                  & Pressure difference between two nodes     &       Pa              \\ \hline
{\ct NODE TEMPERATURE}                          & Temperature of the flow though a node     & $^\circ$C             \\ \hline
{\ct NODE VOLUME FRACTION}                      & Volume fraction of a species in a node    &  mol/mol              \\ \hline
\end{longtable}



\chapter{Alphabetical List of Input Parameters}

This appendix lists all of the input parameters for FDS in separate tables grouped by namelist, these tables are in alphabetical order along with the parameters within them. This is intended to be used as a quick reference and does not replace reading the detailed description of the parameters in the main body of this guide. See Table \ref{tbl:namelistgroups} for a cross-reference of relevant sections and the tables in this appendix. The reason for this statement is that many of the listed parameters are mutually exclusive -- specifying more than one can cause the program to either fail or run in an unpredictable manner. Also, some of the parameters trigger the code to work in a certain mode when specified. For example, specifying the thermal conductivity of a solid surface triggers the code to assume the material to be thermally-thick, mandating that other
properties be specified as well. Simply prescribing as many properties as possible from a handbook is bad practice. Only prescribe those parameters which are necessary to describe the desired scenario. Note that you may use the character string {\ct FYI} on any namelist line to make a note or comment.




\section{\texorpdfstring{{\tt BNDF}}{BNDF} (Boundary File Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Boundary file parameters ({\ct BNDF} namelist group)]{For more information see Section~\ref{info:BNDF}.}
\label{tbl:BNDF} \\
\hline
\multicolumn{5}{|c|}{{\ct BNDF} (Boundary File Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct BNDF} (Boundary File Parameters)} \\
\hline \hline
\endhead
{\ct CELL\_CENTERED}             & Logical     & Section \ref{info:BNDF}                 &           & {\ct .FALSE.}   \\ \hline
{\ct PART\_ID}                   & Character   & Section \ref{info:outputquantities}     &           &                 \\ \hline
{\ct PROP\_ID}                   & Character   & Section \ref{info:BNDF}                 &           &                 \\ \hline
{\ct QUANTITY}                   & Character   & Section \ref{info:outputquantities}     &           &                 \\ \hline
{\ct SPEC\_ID}                   & Character   & Section \ref{info:outputquantities}     &           &                 \\ \hline
{\ct TEMPORAL\_STATISTIC}        & Character   & Section \ref{info:BNDF}                 &           &                 \\ \hline
\end{longtable}


\vspace{\baselineskip}

\section{\texorpdfstring{{\tt CATF}}{CATF} (Concatenate Input Files Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Concatenate Input Files parameters ({\ct CATF} namelist group)]{For more information see Section~\ref{info:CATF}.}
\label{tbl:CATF} \\
\hline
\multicolumn{5}{|c|}{{\ct CATF} (Concatenate Input Files Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct CATF} (Concatenate Input Files Parameters)} \\
\hline \hline
\endhead
{\ct OTHER\_FILES}    & Character Array  & Section \ref{info:CATF}                 &           &   \\ \hline
\end{longtable}

\vspace{\baselineskip}

\section{\texorpdfstring{{\tt CLIP}}{CLIP} (Clipping Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Clipping parameters ({\ct CLIP} namelist group)]{For more information see Section~\ref{info:CLIP}.}
\label{tbl:CLIP} \\
\hline
\multicolumn{5}{|c|}{{\ct CLIP} (Specified Upper and Lower Limits)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct CLIP} (Specified Upper and Lower Limits)} \\
\hline \hline
\endhead
{\ct MAXIMUM\_DENSITY}              & Real           & Section~\ref{info:CLIP}      & kg/m$^3$   &     \\ \hline
{\ct MAXIMUM\_TEMPERATURE}          & Real           & Section~\ref{info:CLIP}      & $^\circ$C  &     \\ \hline
{\ct MINIMUM\_DENSITY}              & Real           & Section~\ref{info:CLIP}      & kg/m$^3$   &     \\ \hline
{\ct MINIMUM\_TEMPERATURE}          & Real           & Section~\ref{info:CLIP}      & $^\circ$C  &     \\ \hline
\end{longtable}

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt COMB}}{COMB} (General Combustion Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[General combustion parameters ({\ct COMB} namelist group)]{For more information see Chapter~\ref{info:COMB}.}
\label{tbl:COMB} \\
\hline
\multicolumn{5}{|c|}{{\ct COMB} (General combustion parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct COMB} (General combustion parameters)} \\
\hline \hline
\endhead
{\ct CHECK\_REALIZABILITY}                      & Logical       & Section~\ref{info:chem_integration}                   &               & {\ct .FALSE.}        \\ \hline
{\ct EXTINCTION\_MODEL}                         & Character     & Section~\ref{info:extinction}                         &               & {\ct 'EXTINCTION 2'} \\ \hline
{\ct FIXED\_MIX\_TIME}                          & Real          & Section~\ref{info:turbulent_combustion}               &  s            &                      \\ \hline
{\ct FUEL\_C\_TO\_CO\_FRACTION}                 & Real          & Section~\ref{info:two-step_simple_chemistry}          &               &  2/3                 \\ \hline
{\ct FUEL\_H\_TO\_H2\_FRACTION}                 & Real          & Section~\ref{info:two-step_simple_chemistry}          &               &  0                   \\ \hline
%{\ct HRRPUV\_MAX\_SMV}                          & Real          & Section~\ref{}                                        &  kW/m$^3$     & 1200                 \\ \hline
{\ct INITIAL\_UNMIXED\_FRACTION}                & Real          & Section~\ref{info:turbulent_combustion}               &               & 1.0                  \\ \hline
{\ct MAX\_CHEMISTRY\_SUBSTEPS}                  & Integer       & Section~\ref{info:chem_integration}                   &               & 20                   \\ \hline
{\ct N\_FIXED\_CHEMISTRY\_SUBSTEPS}             & Integer       & Section~\ref{info:chem_integration}                   &               & -1                   \\ \hline
{\ct N\_SIMPLE\_CHEMISTRY\_REACTIONS}           & Integer       & Section~\ref{info:two-step_simple_chemistry}          &               & 1                    \\ \hline
{\ct ODE\_SOLVER}                               & Character     & Section~\ref{info:chem_integration}                   &               &                      \\ \hline
{\ct RICHARDSON\_ERROR\_TOLERANCE}              & Real          & Section~\ref{info:chem_integration}                   &               & 1.0 E-6              \\ \hline
{\ct SUPPRESSION}                               & Logical       & Section~\ref{info:extinction}                         &               & {\ct .TRUE.}         \\ \hline
{\ct TAU\_CHEM}                                 & Real          & Section~\ref{info:turbulent_combustion}               &               & 1.E-10               \\ \hline
{\ct TAU\_FLAME}                                & Real          & Section~\ref{info:turbulent_combustion}               &               & 1.E10                \\ \hline
%{\ct TEMPERATURE\_DEPENDENT\_REACTION}          & Logical       & Compute mixed zone reactor temperature                &               & {\ct .FALSE.}        \\ \hline
\end{longtable}

\vspace{\baselineskip}



\section{\texorpdfstring{{\tt CSVF}}{CSVF} (Comma Separated Velocity Files)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Comma separated velocity files ({\ct CSVF} namelist group)]{For more information see Section~\ref{info:CSVF}.}
\label{tbl:CSVF} \\
\hline
\multicolumn{5}{|c|}{{\ct CSVF} (Comma Delimited Output Files)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct CSVF} (Comma Delimited Output Files)} \\
\hline \hline
\endhead
%{\ct CSVFILE}         & Character      & Section~\ref{info:??}                &            &     \\ \hline
{\ct UVWFILE}         & Character      & Section~\ref{info:velo_restart}      &            &     \\ \hline
\end{longtable}

\vspace{\baselineskip}



\section{\texorpdfstring{{\tt CTRL}}{CTRL} (Control Function Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Control function parameters ({\ct CTRL} namelist group)]{For more information see Section~\ref{info:CTRL}.}
\label{tbl:CTRL} \\
\hline
\multicolumn{5}{|c|}{{\ct CTRL} (Control Function Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct CTRL} (Control Function Parameters)} \\
\hline \hline
\endhead
{\ct CONSTANT}            & Real       & Section~\ref{info:CONTROL_MATH}         &    &                        \\ \hline
%{\ct CYCLES}             & Integer     & Number of times to cycle output             &    &                    \\ \hline
%{\ct CYCLE\_TIME}        & Real        & Periodicity                                 & s  &                    \\ \hline
{\ct DELAY}              & Real        & Section~\ref{info:dry_pipe}             & s  &  0.                    \\ \hline
{\ct DIFFERENTIAL\_GAIN} & Real        & Section~\ref{info:CONTROL_PID}          &    &  0.                    \\ \hline
{\ct EVACUATION}         & Logical     & Reference~\cite{FDS_Evac_Users_Guide}   &    & {\ct .FALSE.}          \\ \hline
{\ct FUNCTION\_TYPE}     & Character   & Section~\ref{info:basic_control}        &    &                        \\ \hline
{\ct ID}                 & Character   & Section~\ref{info:CTRL}                 &    &                        \\ \hline
{\ct INITIAL\_STATE}     & Logical     & Section~\ref{info:basic_control}        &    & {\ct .FALSE.}          \\ \hline
{\ct INPUT\_ID}          & Char.~Array & Section~\ref{info:CTRL}                 &    &                        \\ \hline
{\ct INTEGRAL\_GAIN}     & Real        & Section~\ref{info:CONTROL_PID}          &    &  0.                    \\ \hline
{\ct LATCH}              & Logical     & Section~\ref{info:basic_control}        &    & {\ct .TRUE.}           \\ \hline
{\ct N}                  & Integer     & Section~\ref{info:CTRL}                 &    &   1                    \\ \hline
{\ct ON\_BOUND}          & Character   & Section~\ref{info:DEADBAND}             &    & {\ct LOWER}            \\ \hline
{\ct PROPORTIONAL\_GAIN} & Real        & Section~\ref{info:CONTROL_PID}          &    &  0.                    \\ \hline
{\ct RAMP\_ID}           & Character   & Section~\ref{info:CUSTOM}               &    &                        \\ \hline
{\ct SETPOINT(2)}        & Real        & Section~\ref{info:basic_control}        &    &                        \\ \hline
{\ct TARGET\_VALUE}      & Real        & Section~\ref{info:CONTROL_PID}          &    &  0.                    \\ \hline
{\ct TRIP\_DIRECTION}    & Integer     & Section~\ref{info:basic_control}        &    &   1                    \\ \hline
\end{longtable}


\vspace{\baselineskip}


\section{\texorpdfstring{{\tt DEVC}}{DEVC} (Device Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Device parameters ({\ct DEVC} namelist group)]{For more information see Section~\ref{info:DEVC}.}
\label{tbl:DEVC} \\
\hline
\multicolumn{5}{|c|}{{\ct DEVC} (Device Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct DEVC} (Device Parameters)} \\
\hline \hline
\endhead
{\ct ABSOLUTE\_VALUE}       & Logical         & Section~\ref{info:out:DEVC}                                     &       & {\ct .FALSE.} \\ \hline
{\ct BYPASS\_FLOWRATE}      & Real            & Section~\ref{info:aspiration_detector}                          & kg/s  & 0             \\ \hline
{\ct CONVERSION\_ADDEND}    & Real            & Section~\ref{info:out:DEVC}                                     &       & 0             \\ \hline
{\ct CONVERSION\_FACTOR}    & Real            & Section~\ref{info:out:DEVC}                                     &       & 1             \\ \hline
{\ct COORD\_FACTOR}         & Real            & Section~\ref{info:line_file}                                    &       & 1             \\ \hline
{\ct CTRL\_ID}              & Character       & Section~\ref{info:RAMPDEVC}                                     &       &               \\ \hline
{\ct DELAY}                 & Real            & Section~\ref{info:aspiration_detector}                          & s     & 0             \\ \hline
{\ct DEPTH}                 & Real            & Section~\ref{info:material_components}                          & m     & 0             \\ \hline
{\ct DEVC\_ID}              & Character       & Sections~\ref{info:aspiration_detector} and \ref{info:RAMPDEVC} &       &               \\ \hline
{\ct D\_ID}                 & Character       & Section~\ref{info:line_file}                                    &       &               \\ \hline
{\ct DRY}                   & Logical         & Section~\ref{info:dry}                                          &       & {\ct .FALSE.} \\ \hline
{\ct DUCT\_ID}              & Character       & Section~\ref{info:HVAC}                                         &       &               \\ \hline
{\ct EVACUATION}            & Logical         & Reference~\cite{FDS_Evac_Users_Guide}                           &       & {\ct .FALSE.} \\ \hline
{\ct FLOWRATE}              & Real            & Section~\ref{info:aspiration_detector}                          & kg/s  & 0             \\ \hline
{\ct HIDE\_COORDINATES}     & Logical         & Section~\ref{info:line_file}                                    &       & {\ct .FALSE.} \\ \hline
{\ct ID}                    & Character       & Section~\ref{info:DEVC}                                         &       &               \\ \hline
{\ct INITIAL\_STATE}        & Logical         & Section~\ref{info:basic_control}                                &       & {\ct .FALSE.} \\ \hline
{\ct INIT\_ID}              & Character       & Section~\ref{info:PART_SURF}                                    &       &               \\ \hline
{\ct IOR}                   & Integer         & Section~\ref{info:DEVC}                                         &       &               \\ \hline
{\ct LATCH}                 & Logical         & Section~\ref{info:basic_control}                                &       & {\ct .TRUE.}  \\ \hline
{\ct MATL\_ID}              & Character       & Section~\ref{info:material_components}                          &       &               \\ \hline
{\ct N\_INTERVALS}          & Integer         & Section~\ref{info:time_integral}                                &       & 10            \\ \hline
{\ct NODE\_ID}              & Character(2)    & Section~\ref{info:HVAC}                                         &       &               \\ \hline
{\ct NO\_UPDATE\_DEVC\_ID}  & Character       & Section~\ref{info:freeze_device}                                &       &               \\ \hline
{\ct NO\_UPDATE\_CTRL\_ID}  & Character       & Section~\ref{info:freeze_device}                                &       &               \\ \hline
{\ct ORIENTATION}           & Real Triplet    & Section~\ref{info:DEVC}                                         &       & 0,0,-1        \\ \hline
{\ct ORIENTATION\_NUMBER}   & Integer         & Section~\ref{info:part_output}                                  &       & 1             \\ \hline
{\ct OUTPUT}                & Logical         & Section~\ref{info:out:DEVC}                                     &       & {\ct .TRUE.}  \\ \hline
{\ct PART\_ID}              & Character       & Section~\ref{info:outputquantities}                             &       &               \\ \hline
{\ct PIPE\_INDEX}           & Integer         & Section~\ref{info:pressureramp}                                 &       &  1            \\ \hline
{\ct POINTS}                & Integer         & Section~\ref{info:line_file}                                    &       & 1             \\ \hline
{\ct PROP\_ID}              & Character       & Section~\ref{info:DEVC}                                         &       &               \\ \hline
{\ct QUANTITY}              & Character       & Section~\ref{info:DEVC}                                         &       &               \\ \hline
{\ct QUANTITY2}             & Character       & Section~\ref{info:line_file}                                    &       &               \\ \hline
{\ct QUANTITY\_RANGE}       & Real(2)         & Section~\ref{info:statistics}                                   &       & -1.E50,1.E50  \\ \hline
{\ct RELATIVE}              & Logical         & Section~\ref{info:out:DEVC}                                     &       & {\ct .FALSE.} \\ \hline
{\ct R\_ID}                 & Character       & Section~\ref{info:line_file}                                    &       &               \\ \hline
{\ct ROTATION}              & Real            & Section~\ref{info:DEVC}                                         & deg.  & 0             \\ \hline
{\ct SETPOINT}              & Real            & Section~\ref{info:basic_control}                                &       &               \\ \hline
{\ct SPATIAL\_STATISTIC}    & Character       & Section~\ref{info:statistics}                                   &       &               \\ \hline
{\ct STATISTICS\_START}     & Real            & Section~\ref{info:rmscovcorr}                                   & s     & {\ct T\_BEGIN}\\ \hline
{\ct STATISTICS\_END}       & Real            & Section~\ref{info:rmscovcorr}                                   & s     & {\ct T\_BEGIN}\\ \hline
{\ct SMOOTHING\_FACTOR}     & Real            & Section~\ref{info:basic_control}                                &       & 0             \\ \hline
{\ct SPEC\_ID}              & Character       & Section~\ref{info:outputquantities}                             &       &               \\ \hline
{\ct SURF\_ID}              & Character       & Section~\ref{info:statistics}                                   &       &               \\ \hline
{\ct TEMPORAL\_STATISTIC}   & Character       & Section~\ref{info:statistics}                                   &       &               \\ \hline
{\ct TIME\_HISTORY}         & Logical         & Section~\ref{info:line_file}                                    &       &               \\ \hline
{\ct TIME\_PERIOD}          & Real            & Section~\ref{info:time_integral}                                & s     &               \\ \hline
{\ct TRIP\_DIRECTION}       & Integer         & Section~\ref{info:basic_control}                                &       &  1            \\ \hline
{\ct UNITS}                 & Character       & Section~\ref{info:out:DEVC}                                     &       &               \\ \hline
{\ct VELO\_INDEX}           & Integer         & Section~\ref{info:velocity}                                     &       &  0            \\ \hline
{\ct XB(6)}                 & Real Sextuplet  & Section~\ref{info:statistics}                                   & m     &               \\ \hline
{\ct XYZ(3)}                & Real Triplet    & Section~\ref{info:DEVC}                                         & m     &               \\ \hline
{\ct X\_ID}                 & Character       & Section~\ref{info:line_file}                                    &       &  {\ct ID-x}   \\ \hline
{\ct Y\_ID}                 & Character       & Section~\ref{info:line_file}                                    &       &  {\ct ID-y}   \\ \hline
{\ct Z\_ID}                 & Character       & Section~\ref{info:line_file}                                    &       &  {\ct ID-z}   \\ \hline
{\ct XYZ\_UNITS}            & Character       & Section~\ref{info:line_file}                                    &       &  {\ct 'm'}    \\ \hline
\end{longtable}


\vspace{\baselineskip}



\section{\texorpdfstring{{\tt DUMP}}{DUMP} (Output Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Output control parameters ({\ct DUMP} namelist group)]{For more information see Section~\ref{info:DUMP}.}
\label{tbl:DUMP} \\
\hline
\multicolumn{5}{|c|}{{\ct DUMP} (Output Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct DUMP} (Output Parameters)} \\
\hline \hline
\endhead
{\ct CFL\_FILE}                     & Logical      & Section~\ref{info:TIME_Control}        &           & {\ct .FALSE.}                  \\ \hline
{\ct CLIP\_RESTART\_FILES}          & Logical      & Section~\ref{info:restart}             &           & {\ct .TRUE.}                   \\ \hline
{\ct COLUMN\_DUMP\_LIMIT}           & Logical      & Section~\ref{info:out:DEVC}            &           & {\ct .FALSE.}                  \\ \hline
{\ct CTRL\_COLUMN\_LIMIT}           & Integer      & Section~\ref{info:out:DEVC}            &           & 254                            \\ \hline
%{\ct CUT\_CELL\_DATA\_FILE}        & Character    & Section~\ref{??}                       &           &                                \\ \hline
{\ct DEVC\_COLUMN\_LIMIT}           & Integer      & Section~\ref{info:out:DEVC}            &           & 254                            \\ \hline
%{\ct DT\_BNDE}                      & Real         & Section~\ref{info:DUMP}                &  s        & $2\,\Delta t${\ct /NFRAMES}    \\ \hline
{\ct DT\_BNDF}                      & Real         & Section~\ref{info:DUMP}                &  s        & $2\,\Delta t${\ct /NFRAMES}    \\ \hline
{\ct DT\_CPU}                       & Real         & Section~\ref{out:CPU}                  &  s        & 1000000                        \\ \hline
{\ct DT\_CTRL}                      & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
{\ct DT\_DEVC}                      & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
{\ct DT\_FLUSH}                     & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
%{\ct DT\_GEOM}                      & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
{\ct DT\_HRR}                       & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
{\ct DT\_ISOF}                      & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
{\ct DT\_MASS}                      & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
{\ct DT\_PART}                      & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
{\ct DT\_PL3D}                      & Real         & Section~\ref{info:DUMP}                &  s        & 1.E10                          \\ \hline
{\ct DT\_PROF}                      & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
{\ct DT\_RESTART}                   & Real         & Section~\ref{info:DUMP}                &  s        & 1000000.                       \\ \hline
{\ct DT\_SL3D}                      & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /5}             \\ \hline
{\ct DT\_SLCF}                      & Real         & Section~\ref{info:DUMP}                &  s        & $\Delta t${\ct /NFRAMES}       \\ \hline
{\ct EB\_PART\_FILE}                & Logical      & Section~\ref{out:PART}                 &           & {\ct .FALSE.}                  \\ \hline
{\ct FLUSH\_FILE\_BUFFERS}          & Logical      & Section~\ref{info:DUMP}                &           & {\ct .TRUE.}                   \\ \hline
{\ct MASS\_FILE}                    & Logical      & Section~\ref{info:DUMP}                &           & {\ct .FALSE.}                  \\ \hline
{\ct MAXIMUM\_PARTICLES}            & Integer      & Section~\ref{info:DUMP}                &           & 1000000                        \\ \hline
{\ct NFRAMES}                       & Integer      & Section~\ref{info:DUMP}                &           & 1000                           \\ \hline
{\ct PLOT3D\_PART\_ID(5)}           & Char.~Quint  & Section~\ref{info:PL3D}                &           &                                \\ \hline
{\ct PLOT3D\_QUANTITY(5)}           & Char.~Quint  & Section~\ref{info:PL3D}                &           &                                \\ \hline
{\ct PLOT3D\_SPEC\_ID(5)}           & Char.~Quint  & Section~\ref{info:PL3D}                &           &                                \\ \hline
{\ct PLOT3D\_VELO\_INDEX}           & Int.~Quint   & Section~\ref{info:velocity}            &           &  0                             \\ \hline
{\ct RENDER\_FILE}                  & Character    & Reference~\cite{Smokeview_Users_Guide} &           &                                \\ \hline
{\ct SIG\_FIGS}                     & Integer      & Section~\ref{info:SIG_FIGS}            &           & 8                              \\ \hline
{\ct SIG\_FIGS\_EXP}                & Integer      & Section~\ref{info:SIG_FIGS}            &           & 3                              \\ \hline
{\ct SMOKE3D}                       & Logical      & Section~\ref{info:SMOKE3D}             &           & {\ct .TRUE.}                   \\ \hline
{\ct SMOKE3D\_QUANTITY}             & Character    & Section~\ref{info:SMOKE3D}             &           &                                \\ \hline
{\ct SMOKE3D\_SPEC\_ID}             & Character    & Section~\ref{info:SMOKE3D}             &           &                                \\ \hline
{\ct STATUS\_FILES}                 & Logical      & Section~\ref{info:DUMP}                &           & {\ct .FALSE.}                  \\ \hline
{\ct SUPPRESS\_DIAGNOSTICS}         & Logical      & Section~\ref{info:monitoring_progress} &           & {\ct .FALSE.}                  \\ \hline
{\ct UVW\_TIMER}                    & Real Vector (10)  & Section~\ref{info:velo_restart}   &  s        &                                \\ \hline
{\ct VELOCITY\_ERROR\_FILE}         & Logical      & Section~\ref{info:TIMING}              &           & {\ct .FALSE.}                  \\ \hline
{\ct WRITE\_XYZ}                    & Logical      & Section~\ref{info:PL3D}                &           & {\ct .FALSE.}                  \\ \hline
\end{longtable}

\noindent
$\Delta t$={\ct T\_END-T\_BEGIN}

\vspace{\baselineskip}

\section{\texorpdfstring{{\tt HEAD}}{HEAD} (Header Parameters)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Header parameters ({\ct HEAD} namelist group)]{For more information see Section~\ref{info:HEAD}.}
\label{tbl:HEAD} \\
\hline
\multicolumn{5}{|c|}{{\ct HEAD} (Header Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct HEAD} (Header Parameters)} \\
\hline \hline
\endhead
{\ct CHID}      & Character   & Section~\ref{info:HEAD}     &           & {\ct 'output'}    \\ \hline
{\ct TITLE}     & Character   & Section~\ref{info:PL3D}     &           &                   \\ \hline
\end{longtable}

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt HOLE}}{HOLE} (Obstruction Cutout Parameters)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Obstruction cutout parameters ({\ct HOLE} namelist group)]{For more information see Section~\ref{info:HOLE}.}
\label{tbl:HOLE} \\
\hline
\multicolumn{5}{|c|}{{\ct HOLE} (Obstruction Cutout Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct HOLE} (Obstruction Cutout Parameters)} \\
\hline \hline
\endhead
{\ct BLOCK\_WIND}  & Logical           & Section~\ref{info:BLOCK_WIND}                          &       &  {\ct .FALSE.}  \\ \hline
{\ct COLOR    }    & Character         & Section~\ref{info:colors}                              &       &                 \\ \hline
{\ct CTRL\_ID}     & Character         & Section~\ref{info:HOLE}                                &       &                 \\ \hline
{\ct DEVC\_ID}     & Character         & Section~\ref{info:HOLE}                                &       &                 \\ \hline
{\ct EVACUATION}   & Logical           & Reference~\cite{FDS_Evac_Users_Guide}                  &       &                 \\ \hline
{\ct ID }          & Character         & Identifier for input line                              &       &                 \\ \hline
{\ct MESH\_ID }    & Character         & Reference~\cite{FDS_Evac_Users_Guide}                  &       &                 \\ \hline
{\ct MULT\_ID }    & Character         & Section~\ref{info:MULT}                                &       &                 \\ \hline
{\ct RGB(3)   }    & Integer Triplet   & Section~\ref{info:colors}                              &       &                 \\ \hline
{\ct TRANSPARENCY} & Real              & Section~\ref{info:HOLE}                                &       &                 \\ \hline
{\ct XB(6)    }    & Real Sextuplet    & Section~\ref{info:MULT}                                & m     &                 \\ \hline
\end{longtable}

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt HVAC}}{HVAC} (HVAC System Definition)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[HVAC parameters ({\ct HVAC} namelist group)]{For more information see Section~\ref{info:HVAC}.}
\label{tbl:HVAC} \\
\hline
\multicolumn{5}{|c|}{{\ct HVAC} (HVAC System Definition)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct HVAC} (HVAC System Definition)} \\
\hline \hline
\endhead
{\ct AIRCOIL\_ID}               & Character         & Section~\ref{info:HVACduct}                                                   &               &                \\ \hline
{\ct AMBIENT}                   & Logical           & Section~\ref{info:HVACnode}                                                   &               & {\ct .FALSE.}  \\ \hline
{\ct AREA}                      & Real              & Section~\ref{info:HVACduct}                                                   & m$^2$         &                \\ \hline
{\ct CLEAN\_LOSS}               & Real              & Section~\ref{info:HVACfilter}                                                 &               &                \\ \hline
{\ct COOLANT\_MASS\_FLOW}       & Real              & Section~\ref{info:HVACaircoil}                                                & kg/s          &                \\ \hline
{\ct COOLANT\_SPECIFIC\_HEAT}   & Real              & Section~\ref{info:HVACaircoil}                                                & \si{kJ/(kg.K)} &               \\ \hline
{\ct COOLANT\_TEMPERATURE}      & Real              & Section~\ref{info:HVACaircoil}                                                & $^\circ$C     &                \\ \hline
{\ct CTRL\_ID}                  & Character         & Sections~\ref{info:HVACduct}, \ref{info:HVACfan}, \ref{info:HVACfilter}       &               &                \\ \hline
{\ct DAMPER}                    & Logical           & Sections~\ref{info:HVACduct}, \ref{info:HVACdamper}                           &               & {\ct .FALSE.}  \\ \hline
{\ct DEVC\_ID}                  & Character         & Sections ~\ref{info:HVACduct}, \ref{info:HVACfan}, \ref{info:HVACfilter}      &               &                \\ \hline
{\ct DIAMETER}                  & Real              & Section~\ref{info:HVACduct}                                                   &  m            &                \\ \hline
{\ct DUCT\_ID}                  & Char.~Array       & Section~\ref{info:HVACnode}                                                   &               &                \\ \hline
{\ct DUCT\_INTERP\_TYPE}        & Character         & Section~\ref{info:hvacmasstransport}                                          &               & {\ct 'NODE1'}  \\ \hline
{\ct EFFICIENCY}                & Real Array        & Sections~\ref{info:HVACfilter}, \ref{info:HVACaircoil}                        &               & 1.0            \\ \hline
{\ct FAN\_ID}                   & Character         & Section~\ref{info:HVACduct}                                                   &               &                \\ \hline
{\ct FILTER\_ID}                & Character         & Section~\ref{info:HVACnode}                                                   &               &                \\ \hline
{\ct FIXED\_Q}                  & Real              & Section~\ref{info:HVACaircoil}                                                & kW            &                \\ \hline
{\ct ID}                        & Character         & Section~\ref{info:HVAC}                                                       &               &                \\ \hline
{\ct LEAK\_ENTHALPY}            & Logical           & Section~\ref{info:local_leakage}                                              &               & {\ct .FALSE.}  \\ \hline
{\ct LENGTH}                    & Real              & Section~\ref{info:HVACduct}                                                   &  m            &                \\ \hline
{\ct LOADING}                   & Real Array        & Section ~\ref{info:HVACfilter}                                                & kg            & 0.0            \\ \hline
{\ct LOADING\_MULTIPLIER}       & Real Array        & Section ~\ref{info:HVACfilter}                                                & 1/kg          & 1.0            \\ \hline
{\ct LOSS}                      & Real Array        & Sections ~\ref{info:HVACduct} -- \ref{info:HVACfilter}                        &               & 0.0            \\ \hline
{\ct MASS\_FLOW  }              & Real              & Section~\ref{info:HVACduct}                                                   &  kg/s         &                \\ \hline
{\ct MAX\_FLOW}                 & Real              & Section ~\ref{info:HVACfan}                                                   &  m$^3$/s      &                \\ \hline
{\ct MAX\_PRESSURE}             & Real              & Section ~\ref{info:HVACfan}                                                   &  Pa           &                \\ \hline
{\ct N\_CELLS}                  & Integer           & Section~\ref{info:hvacmasstransport}                                          &               &{\ct LENGTH}\(/0.1\)  \\ \hline
{\ct NODE\_ID}                  & Char.~Doublet     & Section~\ref{info:HVACduct}                                                   &               &                \\ \hline
{\ct PERIMETER}                 & Real              & Section~\ref{info:HVACduct}                                                   &  m            &                \\ \hline
{\ct RAMP\_ID}                  & Character         & Sections ~\ref{info:HVACduct}, \ref{info:HVACfilter}, \ref{info:HVACfan}      &               &                \\ \hline
{\ct RAMP\_LOSS}                & Character         & Sections~\ref{info:HVACduct}, \ref{info:HVACdamper}                           &               &                \\ \hline
{\ct REVERSE}                   & Logical           & Section~\ref{info:HVACduct}                                                   &               & {\ct .FALSE.}  \\ \hline
{\ct ROUGHNESS}                 & Real              & Section~\ref{info:HVACduct}                                                   &  m            & 0.0            \\ \hline
{\ct SPEC\_ID}                  & Char.~Array       & Section ~\ref{info:HVACfilter}                                                &               &                \\ \hline
{\ct TAU\_AC}                   & Real              & Section ~\ref{info:HVACaircoil}                                               & s             & 1.0            \\ \hline
{\ct TAU\_FAN}                  & Real              & Section ~\ref{info:HVACfan}                                                   & s             & 1.0            \\ \hline
{\ct TAU\_VF}                   & Real              & Section~\ref{info:HVACduct}                                                   & s             & 1.0            \\ \hline
{\ct TYPE\_ID}                  & Character         & Section~\ref{info:HVAC}                                                       &               &                \\ \hline
{\ct VENT\_ID}                  & Character         & Section~\ref{info:HVACnode}                                                   &               &                \\ \hline
{\ct VENT2\_ID}                 & Character         & Section~\ref{info:local_leakage}                                              &               &                \\ \hline
{\ct VOLUME\_FLOW}              & Real              & Section~\ref{info:HVACduct}, \ref{info:HVACfan}                               &  m$^3$/s      &                \\ \hline
{\ct XYZ}                       & Real Triplet      & Section~\ref{info:HVACnode}                                                   &  m            &  0.0           \\ \hline
\end{longtable}


\vspace{\baselineskip}



\section{\texorpdfstring{{\tt INIT}}{INIT} (Initial Conditions)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Initial conditions ({\ct INIT} namelist group)]{For more information see Section~\ref{info:INIT}.}
\label{tbl:INIT} \\
\hline
\multicolumn{5}{|c|}{{\ct INIT} (Initial Conditions)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct INIT} (Initial Conditions)} \\
\hline \hline
\endhead
{\ct AUTO\_IGNITION\_TEMPERATURE} & Real              & Section~\ref{info:extinction}                 & \si{\degree C} & {-273.15}     \\ \hline
{\ct CELL\_CENTERED}              & Logical           & Section~\ref{info:initial_droplets}           &                & {\ct .FALSE.} \\ \hline
{\ct CTRL\_ID}                    & Character         & Section~\ref{info:initial_droplets}           &                &               \\ \hline
{\ct DENSITY}                     & Real              & Section~\ref{info:INIT}                       & kg/m$^3$       & Ambient       \\ \hline
{\ct DEVC\_ID}                    & Character         & Section~\ref{info:initial_droplets}           &                &               \\ \hline
{\ct DIAMETER}                    & Real              & Section~\ref{info:initial_droplets}           & \si{\micro m}  &               \\ \hline
{\ct DT\_INSERT}                  & Real              & Section~\ref{info:initial_droplets}           & s              &               \\ \hline
{\ct DX}                          & Real              & Section~\ref{info:initial_droplets}           & m              & 0.            \\ \hline
{\ct DY}                          & Real              & Section~\ref{info:initial_droplets}           & m              & 0.            \\ \hline
{\ct DZ}                          & Real              & Section~\ref{info:initial_droplets}           & m              & 0.            \\ \hline
{\ct HEIGHT}                      & Real              & Section~\ref{info:initial_droplets}           & m              &               \\ \hline
{\ct HRRPUV}                      & Real              & Section~\ref{info:INIT}                       & \si{kW/m^3}    &               \\ \hline
{\ct ID}                          & Character         & Section~\ref{info:PART_SURF}                  &                &               \\ \hline
{\ct MASS\_FRACTION(N)}           & Real Array        & Section~\ref{info:INIT}                       & kg/kg          & Ambient       \\ \hline
{\ct MASS\_PER\_TIME}             & Real              & Section~\ref{info:initial_droplets}           & kg/s           &               \\ \hline
{\ct MASS\_PER\_VOLUME}           & Real              & Section~\ref{info:initial_droplets}           & \si{kg/m^3}    & 1             \\ \hline
{\ct MULT\_ID }                   & Character         & Section~\ref{info:MULT}                       &                &               \\ \hline
{\ct N\_PARTICLES}                & Integer           & Section~\ref{info:initial_droplets}           &                & 0             \\ \hline
{\ct N\_PARTICLES\_PER\_CELL}     & Integer           & Section~\ref{info:initial_droplets}           &                & 0             \\ \hline
{\ct PART\_ID}                    & Character         & Section~\ref{info:initial_droplets}           &                &               \\ \hline
{\ct PARTICLE\_WEIGHT\_FACTOR}    & Real              & Section~\ref{info:initial_droplets}           &                & 1.            \\ \hline
{\ct RADIUS}                      & Real              & Section~\ref{info:initial_droplets}           & m              &               \\ \hline
{\ct SHAPE}                       & Character         & Section~\ref{info:initial_droplets}           &                & {\ct 'BLOCK'} \\ \hline
{\ct SPEC\_ID(N)}                 & Character Array   & Section~\ref{info:INIT}                       &                &               \\ \hline
{\ct TEMPERATURE}                 & Real              & Section~\ref{info:INIT}                       & \si{\degree C} & {\ct TMPA}    \\ \hline
{\ct UNIFORM}                     & Logical           & Section~\ref{info:initial_droplets}           &                & {\ct .FALSE.} \\ \hline
{\ct UVW(3)}                      & Real Triplet      & Section~\ref{info:initial_droplets}           & m/s            & 0.            \\ \hline
{\ct VOLUME\_FRACTION(N)}         & Real Array        & Section~\ref{info:INIT}                       & mol/mol        & Ambient       \\ \hline
{\ct XB(6)}                       & Real Sextuplet    & Section~\ref{info:INIT}                       & m              &               \\ \hline
{\ct XYZ(3)}                      & Real Triplet      & Section~\ref{info:initial_droplets}           & m              &               \\ \hline
\end{longtable}


\vspace{\baselineskip}



\section{\texorpdfstring{{\tt ISOF}}{ISOF} (Isosurface Parameters)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Isosurface parameters ({\ct ISOF} namelist group)]{For more information see Section~\ref{info:ISOF}.}
\label{tbl:ISOF} \\
\hline
\multicolumn{5}{|c|}{{\ct ISOF} (Isosurface Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct ISOF} (Isosurface Parameters)} \\
\hline \hline
\endhead
{\ct DELTA}                 & Real          & Section~\ref{info:ISOF}                   &       &         \\ \hline
{\ct QUANTITY}              & Character     & Section~\ref{info:ISOF}                   &       &         \\ \hline
{\ct QUANTITY2}             & Character     & Section~\ref{info:ISOF}                   &       &         \\ \hline
{\ct REDUCE\_TRIANGLES}     & Integer       & Reference~\cite{Smokeview_Users_Guide}    &       & 1       \\ \hline
{\ct SPEC\_ID}              & Character     & Section~\ref{info:ISOF}                   &       &         \\ \hline
{\ct SPEC\_ID2}             & Character     & Section~\ref{info:ISOF}                   &       &         \\ \hline
{\ct SKIP}                  & Character     & Section~\ref{info:ISOF}                   &       &         \\ \hline
{\ct SPEC\_ID}              & Character     & Section~\ref{info:ISOF}                   &       &         \\ \hline
{\ct VALUE(I)}              & Real Array    & Section~\ref{info:ISOF}                   &       &         \\ \hline
{\ct VELO\_INDEX}           & Integer       & Section~\ref{info:velocity}               &       &  0      \\ \hline
{\ct VELO\_INDEX2}          & Integer       & Section~\ref{info:velocity}               &       &  0      \\ \hline
\end{longtable}


\vspace{\baselineskip}


\section{\texorpdfstring{{\tt MATL}}{MATL} (Material Properties)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Material properties ({\ct MATL} namelist group)]{For more information see Section~\ref{info:MATL}.}
\label{tbl:MATL} \\
\hline
\multicolumn{5}{|c|}{{\ct MATL} (Material Properties)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct MATL} (Material Properties)} \\
\hline \hline
\endhead
{\ct A(:)}                          & Real array    & Section~\ref{info:solid_pyrolysis}    &    1/s            &        \\ \hline
{\ct ABSORPTION\_COEFFICIENT}       & Real          & Section~\ref{info:thermal_properties} &    1/m            & 50000. \\ \hline
{\ct ALLOW\_SHRINKING}              & Logical       & Section~\ref{info:shrink_swell}       &                   & {\ct.TRUE.} \\ \hline
{\ct ALLOW\_SWELLING}               & Logical       & Section~\ref{info:shrink_swell}       &                   & {\ct.TRUE.} \\ \hline
{\ct BOILING\_TEMPERATURE}          & Real          & Section~\ref{info:liquid_fuels}       & $^\circ$C         & 5000.  \\ \hline
{\ct CONDUCTIVITY}                  & Real          & Section~\ref{info:thermal_properties} & \si{W/(m.K)}      & 0.     \\ \hline
{\ct CONDUCTIVITY\_RAMP}            & Character     & Section~\ref{info:thermal_properties} &                   &        \\ \hline
{\ct DENSITY}                       & Real          & Section~\ref{info:thermal_properties} & kg/m$^3$          & 0.     \\ \hline
{\ct DIFFUSIVITY\_SPEC(:)}          & Real          & Section~\ref{info:pyro3d}             & \si{m^2/2}        &        \\ \hline
{\ct E(:)}                          & Real array    & Section~\ref{info:solid_pyrolysis}    & J/mol             &        \\ \hline
{\ct EMISSIVITY    }                & Real          & Section~\ref{info:thermal_properties} &                   & 0.9    \\ \hline
{\ct GAS\_DIFFUSION\_DEPTH(:) }     & Real array    & Section~\ref{info:solid_pyrolysis}    & m                 & 0.001  \\ \hline
{\ct HEATING\_RATE(:)}              & Real array    & Section~\ref{info:solid_pyrolysis}    & $^\circ$C/min     & 5.     \\ \hline
{\ct HEAT\_OF\_COMBUSTION(:,:)}     & Real array    & Section~\ref{info:solid_pyrolysis}    & kJ/kg             &        \\ \hline
{\ct HEAT\_OF\_REACTION(:)}         & Real array    & Section~\ref{info:solid_pyrolysis}    & kJ/kg             & 0.     \\ \hline
{\ct ID     }                       & Character     & Section~\ref{info:SURF_MATL_Basics}   &                   &        \\ \hline
{\ct MATL\_ID(:,:)}                 & Character     & Section~\ref{info:solid_pyrolysis}    &                   &        \\ \hline
{\ct NU\_MATL(:,:)}                 & Real array    & Section~\ref{info:solid_pyrolysis}    & kg/kg             & 0.     \\ \hline
{\ct NU\_SPEC(:,:)}                 & Real array    & Section~\ref{info:solid_pyrolysis}    & kg/kg             & 0.     \\ \hline
{\ct N\_REACTIONS}                  & Integer       & Section~\ref{info:solid_pyrolysis}    &                   & 0      \\ \hline
{\ct N\_O2(:)}                      & Real array    & Section~\ref{info:solid_pyrolysis}    &                   & 0.     \\ \hline
{\ct N\_S(:)}                       & Real array    & Section~\ref{info:solid_pyrolysis}    &                   & 1.     \\ \hline
{\ct N\_T(:)}                       & Real array    & Section~\ref{info:solid_pyrolysis}    &                   & 0.     \\ \hline
{\ct PCR(:)}                        & Logical array & Section~\ref{info:solid_pyrolysis}    &                   & {\ct.FALSE.}\\ \hline
{\ct PYROLYSIS\_RANGE(:)}           & Real array    & Section~\ref{info:solid_pyrolysis}    & $^\circ$C         & 80.    \\ \hline
{\ct REFERENCE\_RATE(:)}            & Real array    & Section~\ref{info:solid_pyrolysis}    & 1/s               &        \\ \hline
{\ct REFERENCE\_TEMPERATURE(:)}     & Real array    & Section~\ref{info:solid_pyrolysis}    & $^\circ$C         &        \\ \hline
{\ct SPECIFIC\_HEAT}                & Real          & Section~\ref{info:thermal_properties} & \si{kJ/(kg.K)}    & 0.     \\ \hline
{\ct SPECIFIC\_HEAT\_RAMP}          & Character     & Section~\ref{info:thermal_properties} &                   &        \\ \hline
{\ct SPEC\_ID(:,:)}                 & Character     & Section~\ref{info:solid_pyrolysis}    &                   &        \\ \hline
{\ct THRESHOLD\_SIGN(:)}            & Real array    & Section~\ref{info:solid_pyrolysis}    &                   & 1.0    \\ \hline
{\ct THRESHOLD\_TEMPERATURE(:)}     & Real array    & Section~\ref{info:solid_pyrolysis}    & $^\circ$C         & -273.15 \\ \hline
\end{longtable}

\vspace{\baselineskip}



\section{\texorpdfstring{{\tt MESH}}{MESH} (Mesh Parameters)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Mesh parameters ({\ct MESH} namelist group)]{For more information see Section~\ref{info:MESH}.}
\label{tbl:MESH} \\
\hline
\multicolumn{5}{|c|}{{\ct MESH} (Mesh Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct MESH} (Mesh Parameters)} \\
\hline \hline
\endhead
{\ct CHECK\_MESH\_ALIGNMENT}         & Logical                       & Section~\ref{info:mesh_alignment}        &    & {\ct .FALSE.}    \\ \hline
{\ct COLOR}                          & Character                     & Section~\ref{info:multimesh}              &    & {\ct 'BLACK'}    \\ \hline
{\ct CYLINDRICAL}                    & Logical                       & Section~\ref{info:2D}                     &    & {\ct .FALSE.}    \\ \hline
{\ct EVACUATION}                     & Logical                       & Reference~\cite{FDS_Evac_Users_Guide}     &    & {\ct .FALSE.}    \\ \hline
{\ct EVAC\_HUMANS}                   & Logical                       & Reference~\cite{FDS_Evac_Users_Guide}     &    & {\ct .FALSE.}    \\ \hline
{\ct EVAC\_Z\_OFFSET}                & Real                          & Reference~\cite{FDS_Evac_Users_Guide}     & m  & 1                \\ \hline
{\ct ID}                             & Character                     & Reference~\cite{FDS_Evac_Users_Guide}     &    &                  \\ \hline
{\ct IJK}                            & Integer Triplet               & Section~\ref{info:MESH_Basics}            &    & 10,10,10         \\ \hline
{\ct LEVEL}                          & Integer                       & For future use                            &    & 0                \\ \hline
{\ct MPI\_PROCESS}                   & Integer                       & Section~\ref{info:multimesh}              &    &                  \\ \hline
{\ct N\_THREADS}                     & Integer                       & Section~\ref{info:multimesh}              &    &                  \\ \hline
{\ct MULT\_ID }                      & Character                     & Section~\ref{info:MULT}                   &    &                  \\ \hline
{\ct RGB}                            & Integer Triplet               & Section~\ref{info:multimesh}              &    & 0,0,0            \\ \hline
{\ct XB(6)}                          & Real Sextuplet                & Section~\ref{info:MESH_Basics}            & m  & 0,1,0,1,0,1      \\ \hline
\end{longtable}


\vspace{\baselineskip}



\section{\texorpdfstring{{\tt MISC}}{MISC} (Miscellaneous Parameters)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Miscellaneous parameters ({\ct MISC} namelist group)]{For more information see Section~\ref{info:MISC}.}
\label{tbl:MISC} \\
\hline
\multicolumn{5}{|c|}{{\ct MISC} (Miscellaneous Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct MISC} (Miscellaneous Parameters)} \\
\hline \hline
\endhead
%{\ct AEROSOL\_AL2O3}                            & Logical       &                                                       &               & {\ct .FALSE.}     \\ \hline
{\ct AGGLOMERATION}                             & Logical       & Section~\ref{info:agglomeration}                      &               & {\ct .TRUE.}      \\ \hline
{\ct \footnotesize ALLOW\_SURFACE\_PARTICLES}   & Logical       & Section~\ref{info:surface_droplets}                   &               & {\ct .TRUE.}      \\ \hline
{\ct \footnotesize ALLOW\_UNDERSIDE\_PARTICLES} & Logical       & Section~\ref{info:surface_droplets}                   &               & {\ct .FALSE.}     \\ \hline
{\ct \footnotesize ASSUMED\_GAS\_TEMPERATURE}   & Real          & Section~\ref{solid_phase_verification}                & $^\circ$C     &                   \\ \hline
{\ct \footnotesize ASSUMED\_GAS\_TEMPERATURE\_RAMP}& Character  & Section~\ref{solid_phase_verification}                &               &                   \\ \hline
{\ct BAROCLINIC}                                & Logical       & Section~\ref{baroclinic_torque}                       &               & {\ct .TRUE.}      \\ \hline
{\ct BNDF\_DEFAULT}                             & Logical       & Section~\ref{info:BNDF}                               &               & {\ct .TRUE.}      \\ \hline
%{\ct CC\_IBM}                                   & Logical       &                                                       &               & {\ct .FALSE.}     \\ \hline
{\ct C\_DEARDORFF}                              & Real          & Section~\ref{info:LES}                                &               & 0.1               \\ \hline
{\ct C\_SMAGORINSKY}                            & Real          & Section~\ref{info:LES}                                &               & 0.20              \\ \hline
{\ct C\_VREMAN}                                 & Real          & Section~\ref{info:LES}                                &               & 0.07              \\ \hline
{\ct C\_WALE}                                   & Real          & Section~\ref{info:LES}                                &               & 0.60              \\ \hline
{\ct CFL\_MAX}                                  & Real          & Section~\ref{info:CFL}                                &               & 1.0               \\ \hline
{\ct CFL\_MIN}                                  & Real          & Section~\ref{info:CFL}                                &               & 0.8               \\ \hline
{\ct CFL\_VELOCITY\_NORM}                       & Integer       & Section~\ref{info:CFL}                                &               &                   \\ \hline
{\ct CHECK\_HT}                                 & Logical       & Section~\ref{info:HT}                                 &               & {\ct .FALSE.}     \\ \hline
{\ct CHECK\_VN}                                 & Logical       & Section~\ref{info:VN}                                 &               & {\ct .TRUE.}      \\ \hline
{\ct CNF\_CUTOFF}                               & Real          & Section~\ref{info:particle_size}                      &               & 0.005             \\ \hline
{\ct \footnotesize CONSTANT\_SPECIFIC\_HEAT\_RATIO}  & Logical  & Section~\ref{info:Enthalpy}                           &               & {\ct .FALSE.}     \\ \hline
{\ct DEPOSITION}                                & Logical       & Section~\ref{info:deposition}                         &               & {\ct .TRUE.}      \\ \hline
{\ct EVACUATION\_DRILL}                         & Logical       & Reference~\cite{FDS_Evac_Users_Guide}                 &               & {\ct .FALSE.}     \\ \hline
{\ct EVACUATION\_MC\_MODE}                      & Logical       & Reference~\cite{FDS_Evac_Users_Guide}                 &               & {\ct .FALSE.}     \\ \hline
{\ct EVAC\_PRESSURE\_ITERATIONS}                & Integer       & Reference~\cite{FDS_Evac_Users_Guide}                 &               & 50                \\ \hline
{\ct EVAC\_TIME\_ITERATIONS}                    & Integer       & Reference~\cite{FDS_Evac_Users_Guide}                 &               & 50                \\ \hline
%{\ct POSITIVE\_ERROR\_TEST}                     & Logical       & Replace 'ERROR' with 'SUCCESS' label in stderr        &               &  {\ct .FALSE.}    \\ \hline
{\ct FLUX\_LIMITER}                             & Integer       & Section~\ref{info:flux_limiters}                      &               & 2                 \\ \hline
{\ct FREEZE\_VELOCITY}                          & Logical       & Section~\ref{info:freeze_velocity}                    &               & {\ct .FALSE.}     \\ \hline
{\ct GAMMA}                                     & Real          & Section~\ref{gas_species_props}                       &               & 1.4               \\ \hline
{\ct GRAVITATIONAL\_DEPOSITION}                 & Logical       & Section~\ref{info:deposition}                         &               & {\ct .TRUE.}      \\ \hline
{\ct GRAVITATIONAL\_SETTLING}                   & Logical       & Section~\ref{info:deposition}                         &               & {\ct .TRUE.}      \\ \hline
{\ct GVEC}                                      & Real triplet  & Section~\ref{info:GVEC}                               & m/s$^2$       & 0,0,-9.81         \\ \hline
{\ct H\_F\_REFERENCE\_TEMPERATURE}              & Real          & Section~\ref{info:enthalpy}                           & $^\circ$C     & 25.             \\ \hline
{\ct HVAC\_LOCAL\_PRESSURE}                    & Logical       & Section~\ref{info:HVAC}                               &              &  {\ct .TRUE.}     \\ \hline
{\ct HVAC\_MASS\_TRANSPORT}                     & Logical       & Section ~\ref{info:hvacmasstransport}                 &               & {\ct .FALSE.}     \\ \hline
{\ct HVAC\_PRES\_RELAX}                         & Real          & Section ~\ref{info:HVAC}                              &               & 0.5               \\ \hline
{\ct HUMIDITY}                                  & Real          & Section~\ref{info:humidity}                           & \%            & 40.               \\ \hline
{\ct IBLANK\_SMV}                               & Logical       & Section~\ref{info:SLCF}                               &               & {\ct .TRUE.}      \\ \hline
{\ct MAX\_LEAK\_PATHS}                          & Integer       & Section~\ref{info:Leaks}                              &               &  200              \\ \hline
{\ct MAXIMUM\_VISIBILITY}                       & Real          & Section~\ref{info:visibility}                         &  m            &  30               \\ \hline
{\ct MPI\_TIMEOUT}                              & Real          & Section~\ref{info:TIMING}                             &  s            & 10.               \\ \hline
{\ct NEAR\_WALL\_TURBULENCE\_MODEL}             & Character     & Section~\ref{info:LES}                                &               &                   \\ \hline
{\ct NOISE}                                     & Logical       & Section~\ref{info:NOISE}                              &               & {\ct .TRUE.}      \\ \hline
{\ct NOISE\_VELOCITY}                           & Real          & Section~\ref{info:NOISE}                              &  m/s          & 0.005             \\ \hline
{\ct NO\_EVACUATION}                            & Logical       & Reference~\cite{FDS_Evac_Users_Guide}                 &               & {\ct .FALSE.}     \\ \hline
{\ct NO\_RAMPS}                                 & Logical       & Turn off all ramps                                    &               & {\ct .FALSE.}     \\ \hline
{\ct OVERWRITE}                                 & Logical       & Section~\ref{info:OVERWRITE}                          &               & {\ct .TRUE.}      \\ \hline
{\ct PARTICLE\_CFL}                             & Logical       & Section~\ref{info:PART_Stability}                     &               & {\ct .FALSE.}     \\ \hline
{\ct PARTICLE\_CFL\_MAX}                        & Real          & Section~\ref{info:PART_Stability}                     &               & 1.0               \\ \hline
%{\ct PERIODIC\_TEST}                            & Integer       & Initial condition for verification test               &               & 0                 \\ \hline
{\ct POROUS\_FLOOR}                             & Logical       & Section~\ref{info:sprinklers}                         &               & {\ct .TRUE.}      \\ \hline
{\ct PR}                                        & Real          & Section~\ref{info:LES}                                &               & 0.5               \\ \hline
{\ct PROCESS\_ALL\_MESHES}                      & Logical       & Section~\ref{sec:periodic}                            &               & {\ct .FALSE.}     \\ \hline
%{\ct PROCESS\_CUTCELLS}                         & Logical       &                                                       &               & {\ct .TRUE.}     \\ \hline
{\ct PROJECTION}                                & Logical       & Section~\ref{info:CSVF}                               &               & {\ct .FALSE.}     \\ \hline
{\ct P\_INF}                                    & Real          & Section~\ref{info:MISC_Basics}                        & Pa            & 101325            \\ \hline
{\ct RAMP\_GX}                                  & Character     & Section~\ref{info:GVEC}                               &               &                   \\ \hline
{\ct RAMP\_GY}                                  & Character     & Section~\ref{info:GVEC}                               &               &                   \\ \hline
{\ct RAMP\_GZ}                                  & Character     & Section~\ref{info:GVEC}                               &               &                   \\ \hline
{\ct RESTART}                                   & Logical       & Section~\ref{info:restart}                            &               & {\ct .FALSE.}     \\ \hline
{\ct RESTART\_CHID}                             & Character     & Section~\ref{info:restart}                            &               & {\ct CHID}        \\ \hline
{\ct SC}                                        & Real          & Section~\ref{info:LES}                                &               & 0.5               \\ \hline
{\ct SIMULATION\_MODE}                          & Character     & Section~\ref{Sim_Mode}                                &               & {\ct 'VLES'}      \\ \hline
{\ct SHARED\_FILE\_SYSTEM}                      & Logical       & Section~\ref{info:multimesh}                          &               & {\ct .TRUE.}      \\ \hline
{\ct SMOKE\_ALBEDO}                             & Real          & Reference~\cite{Smokeview_Users_Guide}                &               & 0.3               \\ \hline
{\ct SOOT\_OXIDATION}                           & Logical       & Section~\ref{info:deposition}                         &               & {\ct .FALSE.}      \\ \hline
{\ct SOLID\_PHASE\_ONLY}                        & Logical       & Section~\ref{solid_phase_verification}                &               & {\ct .FALSE.}     \\ \hline
%{\ct TENSOR\_DIFFUSIVITY}                       & Logical       &                                                       &               & {\ct .FALSE.}     \\ \hline
%{\ct TERRAIN\_CASE}                             & Logical       & See Wildland Fire User's Guide                        &               & {\ct .FALSE.}     \\ \hline
%{\ct TERRAIN\_IMAGE}                            & Character     & See Wildland Fire User's Guide                        &               &                   \\ \hline
{\ct TAU\_DEFAULT}                              & Real          & Section~\ref{info:RAMP_Time}                          & s             & 1.                \\ \hline
{\ct TEXTURE\_ORIGIN(3)}                        & Real Triplet  & Section~\ref{info:texture_map}                        & m             & (0.,0.,0.)        \\ \hline
{\ct THERMOPHORETIC\_DEPOSITION}                & Logical       & Section~\ref{info:deposition}                         &               & {\ct .TRUE.}      \\ \hline
{\ct THERMOPHORETIC\_SETTLING}                  & Logical       & Section~\ref{info:deposition}                         &               & {\ct .TRUE.}      \\ \hline
{\ct THICKEN\_OBSTRUCTIONS}                     & Logical       & Section~\ref{info:OBST_Basics}                        &               & {\ct .FALSE.}     \\ \hline
{\ct TMPA}                                      & Real          & Section~\ref{info:MISC_Basics}                        & $^\circ$C     & 20.               \\ \hline
{\ct TURBULENCE\_MODEL}                         & Character     & Section~\ref{info:LES}                                &               & {\ct 'DEARDORFF'} \\ \hline
{\ct TURBULENT\_DEPOSITION}                     & Logical       & Section~\ref{info:deposition}                         &               & {\ct .TRUE.}      \\ \hline
%{\ct UVW\_FILE}                                 & Character     & See FDS Verification Guide                            &               &                   \\ \hline
%{\ct VEG\_LEVEL\_SET                            & Logical       & See Wildland Fire User's Guide                        &               & {\ct .FALSE.}     \\ \hline
{\ct VERBOSE}                                   & Logical       & Section~\ref{info:multimesh}                          &               &                   \\ \hline
{\ct VISIBILITY\_FACTOR}                        & Real          & Section~\ref{info:visibility}                         &               & 3                 \\ \hline
{\ct VN\_MAX}                                   & Real          & Section~\ref{info:VN}                                 &               & 1.0               \\ \hline
{\ct VN\_MIN}                                   & Real          & Section~\ref{info:VN}                                 &               & 0.8               \\ \hline
{\ct Y\_CO2\_INFTY}                             & Real          & Section~\ref{info:simple_chemistry}                   &  kg/kg        &                   \\ \hline
{\ct Y\_O2\_INFTY}                              & Real          & Section~\ref{info:simple_chemistry}                   &  kg/kg        &                   \\ \hline
%{\ct WIND\_ONLY}                                & Logical       & See Wildland Fire User's Guide                        &               & {\ct .FALSE.}     \\ \hline
\end{longtable}


\vspace{\baselineskip}


\section{\texorpdfstring{{\tt MOVE}}{MOVE} (Coordinate Transformation Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Coordinate transformation parameters ({\ct MULT} namelist group)]{For more information see Section~\ref{info:MOVE}.}
\label{tbl:MOVE} \\
\hline
\multicolumn{5}{|c|}{{\ct MOVE} (Coordinate Transformation Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct MOVE} (Coordinate Transformation Parameters)} \\
\hline \hline
\endhead
{\ct AXIS(1:3)}       & Real Triplet     & Axis of rotation                                &        & (0,0,1)                    \\ \hline
{\ct DX}              & Real             & Translation in the $x$ direction                & m      & 0.                         \\ \hline
{\ct DY}              & Real             & Translation in the $y$ direction                & m      & 0.                         \\ \hline
{\ct DZ}              & Real             & Translation in the $z$ direction                & m      & 0.                         \\ \hline
{\ct ID }             & Character        & Identification tag                              &        &                            \\ \hline
{\ct ROTATION\_ANGLE} & Real             & Angle of rotation about {\ct AXIS}              & deg.   & 0.                         \\ \hline
{\ct X0}              & Real             & $x$ origin                                      & m      & 0.                         \\ \hline
{\ct Y0}              & Real             & $y$ origin                                      & m      & 0.                         \\ \hline
{\ct Z0}              & Real             & $z$ origin                                      & m      & 0.                         \\ \hline
\end{longtable}


\vspace{\baselineskip}

\section{\texorpdfstring{{\tt MULT}}{MULT} (Multiplier Function Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Multiplier function parameters ({\ct MULT} namelist group)]{For more information see Section~\ref{info:MULT}.}
\label{tbl:MULT} \\
\hline
\multicolumn{5}{|c|}{{\ct MULT} (Multiplier Function Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct MULT} (Multiplier Function Parameters)} \\
\hline \hline
\endhead
{\ct DX}             & Real             & Spacing in the $x$ direction                & m  & 0.                         \\ \hline
{\ct DXB}            & Real Sextuplet   & Spacing for all 6 coordinates               & m  & 0.                         \\ \hline
{\ct DX0}            & Real             & Translation in the $x$ direction            & m  & 0.                         \\ \hline
{\ct DY}             & Real             & Spacing in the $y$ direction                & m  & 0.                         \\ \hline
{\ct DY0}            & Real             & Translation in the $y$ direction            & m  & 0.                         \\ \hline
{\ct DZ}             & Real             & Spacing in the $z$ direction                & m  & 0.                         \\ \hline
{\ct DZ0}            & Real             & Translation in the $z$ direction            & m  & 0.                         \\ \hline
{\ct ID }            & Character        & Identification tag                          &    &                            \\ \hline
{\ct I\_LOWER}       & Integer          & Lower array bound, $x$ direction            &    & 0                          \\ \hline
{\ct I\_LOWER\_SKIP} & Integer          & Lower array bound begin skip, $x$ direction &    &                            \\ \hline
{\ct I\_UPPER}       & Integer          & Upper array bound, $x$ direction            &    & 0                          \\ \hline
{\ct I\_UPPER\_SKIP} & Integer          & Upper array bound end skip, $x$ direction   &    &                            \\ \hline
{\ct J\_LOWER}       & Integer          & Lower array bound, $y$ direction            &    & 0                          \\ \hline
{\ct J\_LOWER\_SKIP} & Integer          & Lower array bound begin skip, $y$ direction &    &                            \\ \hline
{\ct J\_UPPER}       & Integer          & Upper array bound, $y$ direction            &    & 0                          \\ \hline
{\ct J\_UPPER\_SKIP} & Integer          & Upper array bound end skip, $y$ direction   &    &                            \\ \hline
{\ct K\_LOWER}       & Integer          & Lower array bound, $z$ direction            &    & 0                          \\ \hline
{\ct K\_LOWER\_SKIP} & Integer          & Lower array bound begin skip, $z$ direction &    &                            \\ \hline
{\ct K\_UPPER}       & Integer          & Upper array bound, $z$ direction            &    & 0                          \\ \hline
{\ct K\_UPPER\_SKIP} & Integer          & Upper array bound end skip, $z$ direction   &    &                            \\ \hline
{\ct N\_LOWER}       & Integer          & Lower sequence bound                        &    & 0                          \\ \hline
{\ct N\_LOWER\_SKIP} & Integer          & Lower sequence bound begin skip             &    &                            \\ \hline
{\ct N\_UPPER}       & Integer          & Upper sequence bound                        &    & 0                          \\ \hline
{\ct N\_UPPER\_SKIP} & Integer          & Upper sequence bound end skip               &    &                            \\ \hline
\end{longtable}


\vspace{\baselineskip}



\section{\texorpdfstring{{\tt OBST}}{OBST} (Obstruction Parameters)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Obstruction parameters ({\ct OBST} namelist group)]{For more information see Section~\ref{info:OBST}.}
\label{tbl:OBST} \\
\hline
\multicolumn{5}{|c|}{{\ct OBST} (Obstruction Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct OBST} (Obstruction Parameters)} \\
\hline \hline
\endhead
{\ct ALLOW\_VENT}         & Logical             & Section~\ref{info:OBST_Basics}            &           & {\ct .TRUE.}  \\ \hline
{\ct BNDF\_FACE(-3:3)}    & Logical Array       & Section~\ref{info:BNDF}                   &           & {\ct .TRUE.}  \\ \hline
{\ct BNDF\_OBST}          & Logical             & Section~\ref{info:BNDF}                   &           & {\ct .TRUE.}  \\ \hline
{\ct BULK\_DENSITY}       & Real                & Section~\ref{info:BURN_AWAY}              & kg/m$^3$  &               \\ \hline
{\ct COLOR    }           & Character           & Section~\ref{info:OBST_Basics}            &           &               \\ \hline
{\ct CTRL\_ID }           & Character           & Section~\ref{info:activate_deactivate}    &           &               \\ \hline
{\ct DEVC\_ID }           & Character           & Section~\ref{info:activate_deactivate}    &           &               \\ \hline
{\ct EVACUATION}          & Logical             & Reference~\cite{FDS_Evac_Users_Guide}     &           & {\ct .FALSE.} \\ \hline
{\ct HEIGHT}              & Real                & Section~\ref{info:multobst}               & m         &               \\ \hline
{\ct HT3D}                & Logical             & Section~\ref{info:ht3d}                   &           & {\ct .FALSE.} \\ \hline
{\ct ID }                 & Character           & Section~\ref{info:OBST_Basics}            &           &               \\ \hline
{\ct MESH\_ID}            & Character           & Reference~\cite{FDS_Evac_Users_Guide}     &           &               \\ \hline
{\ct MULT\_ID }           & Character           & Section~\ref{info:MULT}                   &           &               \\ \hline
%{\ct NOTERRAIN}           & Logical             & See Wildland Fire User's Guide            &           & {\ct .FALSE.} \\ \hline
{\ct ORIENTATION}         & Real Triplet        & Section~\ref{info:multobst}               & m         & (0.,0.,1.)    \\ \hline
{\ct OUTLINE}             & Logical             & Section~\ref{info:OBST_Basics}            &           & {\ct .FALSE.} \\ \hline
{\ct OVERLAY}             & Logical             & Section~\ref{info:OBST_Basics}            &           & {\ct .TRUE.}  \\ \hline
{\ct PERMIT\_HOLE}        & Logical             & Section~\ref{info:HOLE}                   &           & {\ct .TRUE.}  \\ \hline
{\ct PROP\_ID}            & Character           & Reference~\cite{Smokeview_Users_Guide}    &           &               \\ \hline
{\ct PYRO3D\_IOR}         & Integer             & Section~\ref{info:pyro3d}                 &           & 0             \\ \hline
%{\ct PYRO3D\_MASS\_TRANSPORT}  & Logical        & Section~\ref{info:pyro3d}                 &           & .FALSE.       \\ \hline
{\ct RADIUS}              & Real                & Section~\ref{info:multobst}               & m         &               \\ \hline
{\ct REMOVABLE}           & Logical             & Section~\ref{info:HOLE}                   &           & {\ct .TRUE.}  \\ \hline
{\ct RGB(3)}              & Integer Triplet     & Section~\ref{info:OBST_Basics}            &           &               \\ \hline
{\ct SHAPE}               & Character           & Section~\ref{info:multobst}               &           &               \\ \hline
{\ct SURF\_ID}            & Character           & Section~\ref{info:OBST_Basics}            &           &               \\ \hline
{\ct SURF\_ID6(6)}        & Character Sextuplet & Section~\ref{info:OBST_Basics}            &           &               \\ \hline
{\ct SURF\_IDS(3)}        & Character Triplet   & Section~\ref{info:OBST_Basics}            &           &               \\ \hline
{\ct TEXTURE\_ORIGIN(3)}  & Real Triplet        & Section~\ref{info:texture_map}            & m         & (0.,0.,0.)    \\ \hline
{\ct THICKEN}             & Logical             & Section~\ref{info:OBST_Basics}            &           & {\ct .FALSE.} \\ \hline
{\ct TRANSPARENCY}        & Real                & Section~\ref{info:OBST_Basics}            &           &  1            \\ \hline
{\ct XB(6) }              & Real Sextuplet      & Section~\ref{info:OBST_Basics}            & m         &               \\ \hline
{\ct XYZ(3) }             & Real Triplet        & Section~\ref{info:multobst}               & m         & (0.,0.,0.)    \\ \hline
\end{longtable}


\vspace{\baselineskip}


\section{\texorpdfstring{{\tt PART}}{PART} (Lagrangian Particles/Droplets)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Lagrangian particles ({\ct PART} namelist group)]{For more information see Chapter~\ref{info:PART}.}
\label{tbl:PART} \\
\hline
\multicolumn{5}{|c|}{{\ct PART} (Lagrangian Particles/Droplets)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct PART} (Lagrangian Particles/Droplets)} \\
\hline \hline
\endhead
{\ct AGE}                                & Real            & Section~\ref{info:part_output}          & s         & $1\times 10^5$ \\ \hline
{\ct BREAKUP}                            & Logical         & Section~\ref{info:secondary_breakup}    &           & {\ct .FALSE.} \\ \hline
{\ct BREAKUP\_CNF\_RAMP\_ID}             & Character       & Section~\ref{info:secondary_breakup}    &           &               \\ \hline
{\ct BREAKUP\_DISTRIBUTION}              & Character       & Section~\ref{info:secondary_breakup}    &           & {\ct 'ROSIN...'} \\ \hline
{\ct BREAKUP\_GAMMA\_D}                  & Real            & Section~\ref{info:secondary_breakup}    &           & 2.4           \\ \hline
{\ct BREAKUP\_RATIO}                     & Real            & Section~\ref{info:secondary_breakup}    &           & $3/7$         \\ \hline
{\ct BREAKUP\_SIGMA\_D}                  & Real            & Section~\ref{info:secondary_breakup}    &           &               \\ \hline
{\ct CHECK\_DISTRIBUTION}                & Logical         & Section~\ref{info:particle_size}        &           & {\ct .FALSE.} \\ \hline
{\ct CNF\_RAMP\_ID}                      & Character       & Section~\ref{info:particle_size}        &           &               \\ \hline
{\ct COLOR}                              & Character       & Section~\ref{info:part_output}          &           & {\ct 'BLACK'} \\ \hline
{\ct COMPLEX\_REFRACTIVE\_INDEX}         & Real            & Section~\ref{radiative_part_props}      &           & 0.01          \\ \hline
{\ct CTRL\_ID}                           & Character       & Section~\ref{info:particle_flux}        &           &               \\ \hline
{\ct DENSE\_VOLUME\_FRACTION}            & Real            & Section~\ref{info:DENSE_VOLUME_FRACTION}&           & $1\times 10^{-5}$ \\ \hline
{\ct DEVC\_ID}                           & Character       & Section~\ref{info:particle_flux}        &           &               \\ \hline
{\ct DIAMETER}                           & Real            & Section~\ref{info:particle_size}        & $\mu$m    &               \\ \hline
{\ct DISTRIBUTION}                       & Character       & Section~\ref{info:particle_size}        &           & {\ct 'ROSIN...'} \\ \hline
{\ct DRAG\_COEFFICIENT(3)}               & Real Array      & Section~\ref{info:particle_drag}        &           &               \\ \hline
{\ct DRAG\_LAW}                          & Character       & Section~\ref{info:particle_drag}        &           & {\ct 'SPHERE'}\\ \hline
% {\ct EMBER\_DENSITY\_THRESHOLD}          & Real            & experimental                            & \si{kg/m^3} & 0.0         \\ \hline
% {\ct EMBER\_PARTICLE}                    & Logical         & experimental                            &           & {\ct .FALSE.} \\ \hline
% {\ct EMBER\_VELOCITY\_THRESHOLD}         & Real            & experimental                            & m/s       & Infinite      \\ \hline
{\ct FREE\_AREA\_FRACTION}               & Real            & Section~\ref{info:particle_screen}      &           &               \\ \hline
{\ct GAMMA\_D}                           & Real            & Section~\ref{info:particle_size}        &           & 2.4           \\ \hline
{\ct HEAT\_OF\_COMBUSTION}               & Real            & Section~\ref{info:fuel_droplets}        & kJ/kg     &               \\ \hline
{\ct HORIZONTAL\_VELOCITY}               & Real            & Section~\ref{info:surface_droplets}     & m/s       &  0.2          \\ \hline
{\ct ID}                                 & Character       & Section~\ref{info:PART_Basics}          &           &               \\ \hline
{\ct INITIAL\_TEMPERATURE}               & Real            & Section~\ref{thermal_part_props}        & $^\circ$C & {\ct TMPA}    \\ \hline
{\ct MASSLESS}                           & Logical         & Section~\ref{info:MASSLESS}             &           & {\ct .FALSE.} \\ \hline
{\ct MAXIMUM\_DIAMETER}                  & Real            & Section~\ref{info:particle_size}        & $\mu$m    & Infinite      \\ \hline
{\ct MINIMUM\_DIAMETER}                  & Real            & Section~\ref{info:particle_size}        & $\mu$m    & 20.           \\ \hline
{\ct MONODISPERSE}                       & Logical         & Section~\ref{info:particle_size}        &           & {\ct .FALSE.} \\ \hline
{\ct N\_STRATA}                          & Integer         & Section~\ref{info:particle_size}        &           & 6             \\ \hline
{\ct ORIENTATION(1:3,:)}                 & Real Array      & Section~\ref{info:PART_SURF}            &           &               \\ \hline
{\ct PERIODIC\_X}                        & Logical         & Section~\ref{info:periodic-particles}   &           & {\ct .FALSE.} \\ \hline
{\ct PERIODIC\_Y}                        & Logical         & Section~\ref{info:periodic-particles}   &           & {\ct .FALSE.} \\ \hline
{\ct PERIODIC\_Z}                        & Logical         & Section~\ref{info:periodic-particles}   &           & {\ct .FALSE.} \\ \hline
{\ct PERMEABILITY(3)}                    & Real Array      & Section~\ref{info:porous_media}         &           &               \\ \hline
{\ct POROUS\_VOLUME\_FRACTION}           & Real            & Section~\ref{info:porous_media}         &           &               \\ \hline
{\ct PROP\_ID}                           & Character       & Section~\ref{info:PART_Basics}          &           &               \\ \hline
{\ct QUANTITIES(10)}                     & Character       & Section~\ref{info:part_output}          &           &               \\ \hline
{\ct QUANTITIES\_SPEC\_ID(10)}           & Character       & Section~\ref{info:part_output}          &           &               \\ \hline
{\ct RADIATIVE\_PROPERTY\_TABLE}         & Real            & Section~\ref{radiative_part_props}      &           &               \\ \hline
{\ct REAL\_REFRACTIVE\_INDEX}            & Real            & Section~\ref{radiative_part_props}      &           & 1.33          \\ \hline
{\ct RGB(3)}                             & Integers        & Section~\ref{info:part_output}          &           &               \\ \hline
{\ct RUNNING\_AVERAGE\_FACTOR}           & Real            & Section~\ref{radiative_part_props}      &           & 0.5           \\ \hline
{\ct SAMPLING\_FACTOR}                   & Integer         & Section~\ref{info:part_output}          &           & 1             \\ \hline
{\ct SECOND\_ORDER\_PARTICLE\_TRANSPORT} & Logical         & Section~\ref{info:PART_Stability}       &           & {\ct .FALSE.} \\ \hline
{\ct SHAPE\_FACTOR}                      & Real            & Section~\ref{info:particle_radiation_absorption}&   & 0.25          \\ \hline
{\ct SIGMA\_D}                           & Real            & Section~\ref{info:particle_size}        &           &               \\ \hline
{\ct SPEC\_ID}                           & Character       & Section~\ref{thermal_part_props}        &           &               \\ \hline
{\ct STATIC}                             & Logical         & Section~\ref{info:PART_SURF}            &           & {\ct .FALSE.} \\ \hline
{\ct SURFACE\_TENSION}                   & Real            & Section~\ref{info:secondary_breakup}    & N/m       & $7.28 \times 10^{-2}$  \\ \hline
{\ct SURF\_ID}                           & Character       & Section~\ref{info:PART_SURF}            &           &               \\ \hline
{\ct TURBULENT\_DISPERSION}              & Logical         & Section~\ref{info:MASSLESS}             &           & {\ct .FALSE.} \\ \hline
{\ct VERTICAL\_VELOCITY}                 & Real            & Section~\ref{info:surface_droplets}     & m/s       &  0.5          \\ \hline
\end{longtable}

\vspace{\baselineskip}

\section{\texorpdfstring{{\tt PRES}}{PRES} (Pressure Solver Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Pressure solver parameters ({\ct PRES} namelist group)]{For more information see Section~\ref{info:PRES}.}
\label{tbl:PRES} \\
\hline
\multicolumn{5}{|c|}{{\ct PRES} (Pressure Solver Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct PRES} (Pressure Solver Parameters)} \\
\hline \hline
\endhead
{\ct CHECK\_POISSON}                & Logical       & Section~\ref{pressure_solver}           &               & {\ct .FALSE.}             \\ \hline
{\ct FISHPAK\_BC(3)}                & Integer       & Section~\ref{dancing_eddies}            &               &                           \\ \hline
{\ct ITERATION\_SUSPEND\_FACTOR}    & Real          & Section~\ref{pressure_solver}           & s             & 0.95                      \\ \hline
{\ct MAX\_PRESSURE\_ITERATIONS}     & Integer       & Section~\ref{pressure_solver}           &               & 10                        \\ \hline
{\ct PRESSURE\_RELAX\_TIME}         & Real          & Section~\ref{background_pressure}       & s             & 1.                        \\ \hline
{\ct PRESSURE\_TOLERANCE}           & Real          & Section~\ref{pressure_solver}           & m/s$^2$       &                           \\ \hline
{\ct RELAXATION\_FACTOR}            & Real          & Section~\ref{background_pressure}       &               & 1.                        \\ \hline
{\ct SOLVER}                        & Character     & Section~\ref{optional_pressure_solver}  &               & {\ct 'FFT'}               \\ \hline
{\ct SUSPEND\_PRESSURE\_ITERATIONS} & Logical       & Section~\ref{pressure_solver}           &               & {\ct .TRUE.}              \\ \hline
{\ct VELOCITY\_TOLERANCE}           & Real          & Section~\ref{pressure_solver}           & m/s           &                           \\ \hline
\end{longtable}

% Undocumented: SCARC_METHOD , SCARC_KRYLOV , SCARC_MULTIGRID, SCARC_SMOOTH  , SCARC_PRECON,
%               SCARC_COARSE , SCARC_INITIAL, SCARC_STORAGE  , SCARC_ACCURACY, SCARC_DEBUG ,
%               SCARC_MULTIGRID_CYCLE, SCARC_MULTIGRID_LEVEL , SCARC_MULTIGRID_COARSENING  ,
%               SCARC_MULTIGRID_ITERATIONS  , SCARC_MULTIGRID_ACCURACY   ,
%               SCARC_KRYLOV_ITERATIONS     , SCARC_KRYLOV_ACCURACY      ,
%               SCARC_SMOOTH_ITERATIONS     , SCARC_SMOOTH_ACCURACY      , SCARC_SMOOTH_OMEGA,
%               SCARC_PRECON_ITERATIONS     , SCARC_PRECON_ACCURACY      , SCARC_PRECON_OMEGA,
%               SCARC_COARSE_ITERATIONS     , SCARC_COARSE_ACCURACY

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt PROF}}{PROF} (Wall Profile Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Wall profile parameters ({\ct PROF} namelist group)]{For more information see Section~\ref{info:PROF}.}
\label{tbl:PROF} \\
\hline
\multicolumn{5}{|c|}{{\ct PROF} (Wall Profile Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct PROF} (Wall Profile Parameters)} \\
\hline \hline
\endhead
{\ct FORMAT\_INDEX}         & Integer           & Section~\ref{info:PROF}      &            & 1     \\ \hline
{\ct ID}                    & Character         & Section~\ref{info:PROF}      &            &       \\ \hline
{\ct INIT\_ID}              & Character         & Section~\ref{info:PROF}      &            &       \\ \hline
{\ct IOR}                   & Real              & Section~\ref{info:PROF}      &            &       \\ \hline
{\ct QUANTITY}              & Character         & Section~\ref{info:PROF}      &            &       \\ \hline
{\ct XYZ}                   & Real Triplet      & Section~\ref{info:PROF}      & m          &       \\ \hline
\end{longtable}

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt PROP}}{PROP} (Device Properties)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Device properties ({\ct PROP} namelist group)]{For more information see Section~\ref{info:PROP}.}
\label{tbl:PROP} \\
\hline
\multicolumn{5}{|c|}{{\ct PROP} (Device Properties)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct PROP} (Device Properties)} \\
\hline \hline
\endhead
{\ct ACTIVATION\_OBSCURATION}           & Real          & Section~\ref{info:smoke_detector}         & \%/m                  & 3.24      \\ \hline
{\ct ACTIVATION\_TEMPERATURE}           & Real          & Section~\ref{info:sprinklers}             & $^\circ$C             & 74.        \\ \hline
{\ct ALPHA\_C}                          & Real          & Section~\ref{info:smoke_detector}         &                       & 1.8       \\ \hline
{\ct ALPHA\_E}                          & Real          & Section~\ref{info:smoke_detector}         &                       & 0.       \\ \hline
{\ct BETA\_C}                           & Real          & Section~\ref{info:smoke_detector}         &                       & 1.       \\ \hline
{\ct BETA\_E}                           & Real          & Section~\ref{info:smoke_detector}         &                       & 1.       \\ \hline
{\ct CHARACTERISTIC\_VELOCITY}          & Real          & Section~\ref{info:pressure_coefficient}   & m/s                   & 1.       \\ \hline
{\ct C\_FACTOR}                         & Real          & Section~\ref{info:sprinklers}             & (m/s)$^{1/2}$         & 0.        \\ \hline
{\ct DENSITY}                           & Real          & Section~\ref{info:THERMOCOUPLE}           & kg/m$^3$              & 8908.     \\ \hline
{\ct DIAMETER}                          & Real          & Section~\ref{info:THERMOCOUPLE}           & m                     & 0.001     \\ \hline
{\ct EMISSIVITY}                        & Real          & Section~\ref{info:THERMOCOUPLE}           &                       & 0.85      \\ \hline
{\ct FLOW\_RAMP}                        & Character     & Section~\ref{info:sprinklers}             &                       &           \\ \hline
{\ct FLOW\_RATE}                        & Real          & Section~\ref{info:sprinklers}             & L/min                 &           \\ \hline
{\ct FLOW\_TAU}                         & Real          & Section~\ref{info:sprinklers}             &                       & 0.       \\ \hline
{\ct GAUGE\_EMISSIVITY}                 & Real          & Section~\ref{info:heat_flux}              &                       & 1.        \\ \hline
{\ct GAUGE\_TEMPERATURE}                & Real          & Section~\ref{info:heat_flux}              & $^\circ$C             & {\ct TMPA}\\ \hline
{\ct HEAT\_TRANSFER\_COEFFICIENT}       & Real          & Section~\ref{info:THERMOCOUPLE}           & \si{W/(m$^2$.K)}      &           \\ \hline
{\ct ID}                                & Character     & Section~\ref{info:PROP}                   &                       &           \\ \hline
{\ct INITIAL\_TEMPERATURE}              & Real          & Section~\ref{info:sprinklers}             & $^\circ$C             & {\ct TMPA}\\ \hline
{\ct K\_FACTOR}                         & Real          & Section~\ref{info:sprinklers}             & $\si{L/(min.bar^{\ha})}$ & 1.        \\ \hline
{\ct LENGTH}                            & Real          & Section~\ref{info:smoke_detector}         & m                     & 1.8       \\ \hline
{\ct MASS\_FLOW\_RATE}                  & Real          & Section~\ref{info:sprinklers}             & kg/s                  &           \\ \hline
{\ct OFFSET}                            & Real          & Section~\ref{info:sprinklers}             & m                     & 0.05      \\ \hline
{\ct OPERATING\_PRESSURE}               & Real          & Section~\ref{info:sprinklers}             & bar                   & 1.        \\ \hline
{\ct ORIFICE\_DIAMETER}                 & Real          & Section~\ref{info:sprinklers}             & m                     & 0.       \\ \hline
{\ct P0,PX(3),PXX(3,3)}                 & Real          & Section~\ref{info:velocity_patch}         & m/s                   &  0.         \\ \hline
{\ct PARTICLES\_PER\_SECOND}            & Integer       & Section~\ref{info:sprinklers}             &                       & 5000      \\ \hline
{\ct PARTICLE\_VELOCITY}                & Real          & Section~\ref{info:sprinklers}             & m/s                   & 0.       \\ \hline
{\ct PART\_ID}                          & Character     & Section~\ref{info:sprinklers}             &                       &           \\ \hline
{\ct PDPA\_END}                         & Real          & Section~\ref{PDPA}                        & s                     & {\ct T\_END} \\ \hline
{\ct PDPA\_HISTOGRAM}                   & Logical       & Section~\ref{PDPA}                        &                       & .FALSE.   \\ \hline
{\ct PDPA\_HISTOGRAM\_CUMULATIVE}       & Logical       & Section~\ref{PDPA}                        &                       & .FALSE.   \\ \hline
{\ct PDPA\_HISTOGRAM\_LIMITS}           & Real Array    & Section~\ref{PDPA}                        &                       &       \\ \hline
{\ct PDPA\_HISTOGRAM\_NBINS}            & Integer       & Section~\ref{PDPA}                        &                       & 10        \\ \hline
{\ct PDPA\_INTEGRATE}                   & Logical       & Section~\ref{PDPA}                        &                       & {\ct .TRUE.}         \\ \hline
{\ct PDPA\_M}                           & Integer       & Section~\ref{PDPA}                        &                       & 0         \\ \hline
{\ct PDPA\_N}                           & Integer       & Section~\ref{PDPA}                        &                       & 0         \\ \hline
{\ct PDPA\_NORMALIZE}                   & Logical       & Section~\ref{PDPA}                        &                       & {\ct .TRUE.}         \\ \hline
{\ct PDPA\_RADIUS}                      & Real          & Section~\ref{PDPA}                        & m                     & 0.        \\ \hline
{\ct PDPA\_START}                       & Real          & Section~\ref{PDPA}                        & s                     & 0.        \\ \hline
{\ct PRESSURE\_RAMP}                    & Character     & Section~\ref{info:sprinklers}             &                       &           \\ \hline
{\ct QUANTITY}                          & Character     & Section~\ref{info:sprinklers}             &                       &           \\ \hline
{\ct RTI}                               & Real          & Section~\ref{info:sprinklers}             & $\sqrt{\si{m.s}}$     & 100.      \\ \hline
{\ct SMOKEVIEW\_ID}                     & Char.~Array   & Section~\ref{info:SMOKEVIEW_ID}           &                       &           \\ \hline
{\ct SMOKEVIEW\_PARAMETERS}             & Char.~Array   & Section~\ref{info:SMOKEVIEW_PARAMETERS}   &                       &           \\ \hline
{\ct SPEC\_ID}                          & Character     & Section~\ref{info:alternative_smoke}      &                       &           \\ \hline
{\ct SPECIFIC\_HEAT}                    & Real          & Section~\ref{info:THERMOCOUPLE}           & \si{kJ/(kg.K)}        & 0.44      \\ \hline
{\ct SPRAY\_ANGLE(2,2)}                 & Real          & Section~\ref{info:sprinklers}             & degrees               & 60.,75.   \\ \hline
{\ct SPRAY\_PATTERN\_BETA}              & Real          & Section~\ref{info:sprinklers}             & degrees               & 5.        \\ \hline
{\ct SPRAY\_PATTERN\_MU}                & Real          & Section~\ref{info:sprinklers}             & degrees               & 0.        \\ \hline
{\ct SPRAY\_PATTERN\_SHAPE}             & Character     & Section~\ref{info:sprinklers}             &                       & {\ct 'GAUSSIAN'}  \\ \hline
{\ct SPRAY\_PATTERN\_TABLE}             & Character     & Section~\ref{info:sprinklers}             &                       &           \\ \hline
{\ct VELOCITY\_COMPONENT}               & Integer       & Section~\ref{info:velocity_patch}         &                       &           \\ \hline
\end{longtable}


\vspace{\baselineskip}

\section{\texorpdfstring{{\tt RADF}}{RADF} (Radiation Output File Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Radiation output file parameters ({\ct RADF} namelist group)]{For more information see Section~\ref{info:RADF}.}
\label{tbl:RADF} \\
\hline
\multicolumn{5}{|c|}{{\ct RADF} (Radiation Output File Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct RADF} (Radiation Output File Parameters)} \\
\hline \hline
\endhead
{\ct I\_STEP}                       & Integer              & Section~\ref{info:RADF}            &                   &  1     \\ \hline
{\ct J\_STEP}                       & Integer              & Section~\ref{info:RADF}            &                   &  1     \\ \hline
{\ct K\_STEP}                       & Integer              & Section~\ref{info:RADF}            &                   &  1     \\ \hline
{\ct XB}                            & Real Sextuplet       & Section~\ref{info:RADF}            & m                 &        \\ \hline
\end{longtable}


\vspace{\baselineskip}

\section{\texorpdfstring{{\tt RADI}}{RADI} (Radiation Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Radiation parameters ({\ct RADI} namelist group)]{For more information see Section~\ref{info:RADI}.}
\label{tbl:RADI} \\
\hline
\multicolumn{5}{|c|}{{\ct RADI} (Radiation Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct RADI} (Radiation Parameters)} \\
\hline \hline
\endhead
{\ct ANGLE\_INCREMENT}              & Integer       & Section~\ref{info:RADI_Resolution}        &                   & 5                 \\ \hline
{\ct BAND\_LIMITS    }              & Real Array    & Section~\ref{info:RADI_Wide_Band}         & $\mu$m            &                   \\ \hline
{\ct C\_MAX                   }     & Real          & Section~\ref{info:CHI_R}                  &                   & 100               \\ \hline
{\ct C\_MIN                   }     & Real          & Section~\ref{info:CHI_R}                  &                   & 1                 \\ \hline
{\ct INITIAL\_RADIATION\_ITERATIONS}& Integer       & Section~\ref{info:RADI_Resolution}        &                   & 3                 \\ \hline
{\ct KAPPA0                   }     & Real          & Section~\ref{info:RADI_Absorption}        & 1/m               & 0                 \\ \hline
{\ct MIE\_MINIMUM\_DIAMETER}        & Real          & Section~\ref{info:RADI_Absorption}        & $\mu$m            & 0.5               \\ \hline
{\ct MIE\_MAXIMUM\_DIAMETER}        & Real          & Section~\ref{info:RADI_Absorption}        & $\mu$m            & 1.5$\times D$     \\ \hline
{\ct MIE\_NDG}                      & Integer       & Section~\ref{info:RADI_Absorption}        &                   & 50                \\ \hline
{\ct NMIEANG                  }     & Integer       & Section~\ref{info:RADI_Absorption}        &                   & 15                \\ \hline
{\ct NUMBER\_RADIATION\_ANGLES}     & Integer       & Section~\ref{info:RADI_Resolution}        &                   & 100               \\ \hline
{\ct OPTICALLY\_THIN}               & Logical       & Section~\ref{info:CHI_R}                  &                   & {\ct .FALSE.}     \\ \hline
{\ct PATH\_LENGTH }                 & Real          & Section~\ref{info:RADI_Wide_Band}         &   m               & 0.1               \\ \hline
{\ct QR\_CLIP                  }    & Real          & Section~\ref{info:CHI_R}                  & kW/m$^3$          & 10                \\ \hline
{\ct RADIATION}                     & Logical       & Section~\ref{info:radiation_off}          &                   & {\ct .TRUE.}      \\ \hline
{\ct RADIATION\_ITERATIONS}         & Integer       & Section~\ref{info:RADI_Resolution}        &                   & 1                 \\ \hline
{\ct RADTMP                   }     & Real          & Section~\ref{info:RADI_Absorption}        & $^\circ$C         & 900               \\ \hline
{\ct TIME\_STEP\_INCREMENT}         & Integer       & Section~\ref{info:RADI_Resolution}        &                   & 3                 \\ \hline
{\ct WIDE\_BAND\_MODEL    }         & Logical       & Section~\ref{info:RADI_Wide_Band}         &                   & {\ct .FALSE.}     \\ \hline
\end{longtable}

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt RAMP}}{RAMP} (Ramp Function Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Ramp function parameters ({\ct RAMP} namelist group)]{For more information see Chapter~\ref{info:RAMP}.}
\label{tbl:RAMP} \\
\hline
\multicolumn{5}{|c|}{{\ct RAMP} (Ramp Function Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct RAMP} (Ramp Function Parameters)} \\
\hline \hline
\endhead
{\ct CTRL\_ID}                      & Character     & Section~\ref{info:RAMPDEVC}   &                       &           \\ \hline
{\ct DEVC\_ID}                      & Character     & Section~\ref{info:RAMPDEVC}   &                       &           \\ \hline
{\ct F}                             & Real          & Chapter~\ref{info:RAMP}       &                       &           \\ \hline
{\ct ID}                            & Character     & Chapter~\ref{info:RAMP}       &                       &           \\ \hline
{\ct NUMBER\_INTERPOLATION\_POINTS} & Integer       & Chapter~\ref{info:RAMP}       &                       &  5000     \\ \hline
{\ct T}                             & Real          & Chapter~\ref{info:RAMP}       & s (or $^\circ$C)      &           \\ \hline
{\ct X}                             & Real          & Section~\ref{info:GVEC}       & m                     &           \\ \hline
\end{longtable}

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt REAC}}{REAC} (Reaction Parameters)}
\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Reaction parameters ({\ct REAC} namelist group)]{For more information see Chapter~\ref{chap:combustion}.}
\label{tbl:REAC} \\
\hline
\multicolumn{5}{|c|}{{\ct REAC} (Reaction Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct REAC} (Reaction Parameters)} \\
\hline \hline
\endhead
{\ct A}                                   & Real        & Section~\ref{info:finite}                 &                   &                   \\ \hline
{\ct AUTO\_IGNITION\_TEMPERATURE}         & Real        & Section~\ref{info:extinction}             & $^\circ$C         &                   \\ \hline
{\ct C}                                   & Real        & Section~\ref{info:simple_chemistry}       &                   & 0                 \\ \hline
{\ct CHECK\_ATOM\_BALANCE}                & Logical     & Section~\ref{info:REAC_Diagnostics}       &                   & {\ct .TRUE.}      \\ \hline
{\ct CO\_YIELD}                           & Real        & Section~\ref{info:simple_chemistry}       & kg/kg             & 0                 \\ \hline
{\ct CRITICAL\_FLAME\_TEMPERATURE}        & Real        & Section~\ref{info:extinction}             &   $^\circ$C       & 1427              \\ \hline
{\ct E}                                   & Real        & Section~\ref{info:finite}                 &   J/mol           &                   \\ \hline
{\ct EPUMO2}                              & Real        & Section~\ref{info:heat_of_combustion}     &   kJ/kg           & 13100             \\ \hline
{\ct EQUATION}                            & Character   & Section~\ref{info:EQUATION}               &                   &                   \\ \hline
{\ct FORMULA}                             & Character   & Section~\ref{info:simple_chemistry}       &                   &                   \\ \hline
{\ct FUEL}                                & Character   & Section~\ref{info:simple_chemistry}       &                   &                   \\ \hline
{\ct FUEL\_RADCAL\_ID}                    & Character   & Section~\ref{info:simple_chemistry}       &                   &                   \\ \hline
{\ct H}                                   & Real        & Section~\ref{info:simple_chemistry}       &                   & 0                 \\ \hline
{\ct HEAT\_OF\_COMBUSTION}                & Real        & Section~\ref{info:heat_of_combustion}     & kJ/kg             &                   \\ \hline
{\ct HOC\_COMPLETE}                       & Real        & Section~\ref{info:hoc_complete}           & kJ/kg             &                   \\ \hline
{\ct ID}                                  & Character   & Section~\ref{info:simple_chemistry}       &                   &                   \\ \hline
{\ct IDEAL}                               & Logical     & Section~\ref{info:simple_chemistry}       &                   & {\ct .FALSE.}     \\ \hline
{\ct LOWER\_OXYGEN\_LIMIT}                & Real        & Section~\ref{info:extinction}             & mol/mol           &                   \\ \hline
{\ct N}                                   & Real        & Section~\ref{info:simple_chemistry}       &                   & 0                 \\ \hline
{\ct NU(:)}                               & Real Array  & Section~\ref{info:finite}                 &                   &                   \\ \hline
{\ct N\_S(:)}                             & Real Array  & Section~\ref{info:finite}                 &                   &                   \\ \hline
{\ct N\_T}                                & Real        & Section~\ref{info:finite}                 &                   &                   \\ \hline
{\ct O}                                   & Real        & Section~\ref{info:simple_chemistry}       &                   & 0                 \\ \hline
{\ct PRIORITY}                            & Integer     & Section~\ref{info:priority}               &                   & 1                 \\ \hline
{\ct RADIATIVE\_FRACTION}                 & Real        & Section~\ref{info:CHI_R}                  &                   &                   \\ \hline
{\ct RAMP\_AIT}                           & Character   & Section~\ref{info:ramp_ait}               &                   &                   \\ \hline
{\ct RAMP\_CHI\_R}                        & Character   & Section~\ref{info:CHI_R}                  &                   &                   \\ \hline
{\ct REAC\_ATOM\_ERROR}                   & Real        & Section~\ref{info:REAC_Diagnostics}       & atoms             & 1.E-5             \\ \hline
{\ct REAC\_MASS\_ERROR}                   & Real        & Section~\ref{info:REAC_Diagnostics}       & kg/kg             & 1.E-4             \\ \hline
{\ct SOOT\_H\_FRACTION}                   & Real        & Section~\ref{info:simple_chemistry}       &                   & 0.1               \\ \hline
{\ct SOOT\_YIELD}                         & Real        & Section~\ref{info:simple_chemistry}       & kg/kg             & 0.0               \\ \hline
{\ct SPEC\_ID\_N\_S(:)}                   & Char.~Array & Section~\ref{info:finite}                 &                   &                   \\ \hline
{\ct SPEC\_ID\_NU(:)}                     & Char.~Array & Section~\ref{info:finite}                 &                   &                   \\ \hline
{\ct THIRD\_BODY}                         & Logical     & Section~\ref{info:finite}                 &                   & {\ct .FALSE.}     \\ \hline
\end{longtable}

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt SLCF}}{SLCF} (Slice File Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Slice file parameters ({\ct SLCF} namelist group)]{For more information see Section~\ref{info:SLCF}.}
\label{tbl:SLCF} \\
\hline
\multicolumn{5}{|c|}{{\ct SLCF} (Slice File Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct SLCF} (Slice File Parameters)} \\
\hline \hline
\endhead
{\ct CELL\_CENTERED}    & Logical           & Section~\ref{info:SLCF}                   &           & {\ct .FALSE.}     \\ \hline
{\ct EVACUATION}        & Logical           & Reference~\cite{FDS_Evac_Users_Guide}     &           & {\ct .FALSE.}\\ \hline
{\ct MAXIMUM\_VALUE}    & Real              & Reference~\cite{Smokeview_Users_Guide}    &           &                   \\ \hline
{\ct MESH\_NUMBER}      & Integer           & Section~\ref{info:SLCF}                   &           &                   \\ \hline
{\ct MINIMUM\_VALUE}    & Real              & Reference~\cite{Smokeview_Users_Guide}    &           &                   \\ \hline
{\ct PART\_ID}          & Character         & Section~\ref{info:outputquantities}       &           &                   \\ \hline
{\ct PBX, PBY, PBZ}     & Real              & Section~\ref{info:SLCF}                   & m         &                   \\ \hline
{\ct QUANTITY}          & Character         & Section~\ref{info:outputquantities}       &           &                   \\ \hline
{\ct QUANTITY2}         & Character         & Section~\ref{info:outputquantities}       &           &                   \\ \hline
{\ct SPEC\_ID}          & Character         & Section~\ref{info:outputquantities}       &           &                   \\ \hline
{\ct VECTOR    }        & Logical           & Section~\ref{info:SLCF}                   &           & {\ct .FALSE.}     \\ \hline
{\ct VELO\_INDEX}       & Integer           & Section~\ref{info:velocity}               &           &  0                \\ \hline
{\ct XB(6)}             & Real Sextuplet    & Section~\ref{info:SLCF}                   & m         &                   \\ \hline
\end{longtable}

%Undocumented: AGL_SLICE,FIRE_LINE, ID, LEVEL_SET_FIRE_LINE

\vspace{\baselineskip}

\section{\texorpdfstring{{\tt SPEC}}{SPEC} (Species Parameters)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Species parameters ({\ct SPEC} namelist group)]{For more information see Section~\ref{info:SPEC}.}
\label{tbl:SPEC} \\
\hline
\multicolumn{5}{|c|}{{\ct SPEC} (Species Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct SPEC} (Species Parameters)} \\
\hline \hline
\endhead
{\ct AEROSOL}                       & Logical     & Section~\ref{info:deposition}           &                   & {\ct .FALSE.} \\ \hline
{\ct ALIAS}                         & Character   & Section~\ref{info:SPEC_advanced}        &                   &               \\ \hline
{\ct BACKGROUND}                    & Logical     & Section~\ref{info:SPEC}                 &                   & {\ct .FALSE.} \\ \hline
{\ct CONDUCTIVITY}                  & Real        & Section~\ref{gas_species_props}         & \si{W/(m.K)}      &               \\ \hline
{\ct CONDUCTIVITY\_SOLID}           & Real        & Section~\ref{info:deposition}           & \si{W/(m.K)}      &  0.26         \\ \hline
{\ct DENSITY\_LIQUID}               & Real        & Section~\ref{thermal_part_props}        & kg/m$^3$          &               \\ \hline
{\ct DENSITY\_SOLID}                & Real        & Section~\ref{info:deposition}           & kg/m$^3$          &  1800.        \\ \hline
{\ct DIFFUSIVITY}                   & Real        & Section~\ref{gas_species_props}         & m$^2$/s           &               \\ \hline
{\ct ENTHALPY\_OF\_FORMATION}       & Real        & Section~\ref{thermal_part_props}        & kJ/mol            &               \\ \hline
{\ct EPSILONKLJ}                    & Real        & Section~\ref{gas_species_props}         &                   & 0             \\ \hline
{\ct FIC\_CONCENTRATION}            & Real        & Section~\ref{info:FED}                  & ppm               & 0.            \\ \hline
{\ct FLD\_LETHAL\_DOSE}             & Real        & Section~\ref{info:FED}                  & ppm$\times$min    & 0.            \\ \hline
{\ct FORMULA }                      & Character   & Section~\ref{gas_species_props}         &                   &               \\ \hline
{\ct HEAT\_OF\_VAPORIZATION}        & Real        & Section~\ref{thermal_part_props}        & kJ/kg             &               \\ \hline
{\ct H\_V\_REFERENCE\_TEMPERATURE}  & Real        & Section~\ref{thermal_part_props}        & $^\circ$C         &               \\ \hline
{\ct ID }                           & Character   & Section~\ref{info:SPEC_Basics}          &                   &               \\ \hline
{\ct LUMPED\_COMPONENT\_ONLY}       & Logical     & Section~\ref{info:lumped}               &                   & {\ct .FALSE.} \\ \hline
{\ct MASS\_EXTINCTION\_COEFFICIENT} & Real        & Section~\ref{info:alternative_smoke}    &                   & 0             \\ \hline
{\ct MASS\_FRACTION(:)}             & Real Array  & Section~\ref{info:lumped}               &                   & 0             \\ \hline
{\ct MASS\_FRACTION\_0}             & Real        & Section~\ref{info:SPEC_Basics}          &                   & 0             \\ \hline
{\ct MAX\_DIAMETER}                 & Real        & Section~\ref{info:agglomeration}        &    m              &               \\ \hline
{\ct MEAN\_DIAMETER}                & Real        & Section~\ref{info:deposition}           & m                 & 1.E-6         \\ \hline
{\ct MELTING\_TEMPERATURE}          & Real        & Section~\ref{thermal_part_props}        & $^\circ$C         &               \\ \hline
{\ct MIN\_DIAMETER}                 & Real        & Section~\ref{info:agglomeration}        & m                 &               \\ \hline
{\ct MW}                            & Real        & Section~\ref{gas_species_props}         & g/mol             & 29.           \\ \hline
{\ct N\_BINS}                       & Integer     & Section~\ref{info:agglomeration}        &                   &               \\ \hline
{\ct PR\_GAS}                       & Real        & Section~\ref{gas_species_props}         &                   & {\ct PR}      \\ \hline
{\ct PRIMITIVE}                     & Logical     & Section~\ref{gas_species_props}         &                   &               \\ \hline
{\ct RADCAL\_ID}                    & Character   & Section~\ref{info:SPEC_advanced}        &                   &               \\ \hline
{\ct RAMP\_CP}                      & Character   & Section~\ref{gas_species_props}         &                   &               \\ \hline
{\ct RAMP\_CP\_L}                   & Character   & Section~\ref{thermal_part_props}        &                   &               \\ \hline
{\ct RAMP\_D}                       & Character   & Section~\ref{gas_species_props}         &                   &               \\ \hline
{\ct RAMP\_G\_F}                    & Character   & Section~\ref{gas_species_props}         &                   &               \\ \hline
{\ct RAMP\_K}                       & Character   & Section~\ref{gas_species_props}         &                   &               \\ \hline
{\ct RAMP\_MU}                      & Character   & Section~\ref{gas_species_props}         &                   &               \\ \hline
{\ct REFERENCE\_ENTHALPY}           & Real        & Section~\ref{gas_species_props}         & kJ/kg             &               \\ \hline
{\ct REFERENCE\_TEMPERATURE}        & Real        & Section~\ref{gas_species_props}         & $^\circ$C         & 25.           \\ \hline
{\ct SIGMALJ}                       & Real        & Section~\ref{gas_species_props}         &                   & 0             \\ \hline
{\ct SPEC\_ID(:)}                   & Character Array   & Section~\ref{info:lumped}             &                   &               \\ \hline
{\ct SPECIFIC\_HEAT}                & Real        & Section~\ref{gas_species_props}         & \si{kJ/(kg.K)}    &               \\ \hline
{\ct SPECIFIC\_HEAT\_LIQUID}        & Real        & Section~\ref{thermal_part_props}        & \si{kJ/(kg.K)}    &               \\ \hline
{\ct VAPORIZATION\_TEMPERATURE}     & Real        & Section~\ref{thermal_part_props}        & $^\circ$C         &               \\ \hline
{\ct VISCOSITY}                     & Real        & Section~\ref{gas_species_props}         & \si{kg/(m.s)}     &               \\ \hline
{\ct VOLUME\_FRACTION(:)}           & Real Array        & Section~\ref{info:lumped}             &                   &               \\ \hline
\end{longtable}

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt SURF}}{SURF} (Surface Properties)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Surface properties ({\ct SURF} namelist group)]{For more information see Section~\ref{info:SURF}.}
\label{tbl:SURF} \\
\hline
\multicolumn{5}{|c|}{{\ct SURF} (Surface Properties)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct SURF} (Surface Properties)} \\
\hline \hline
\endhead
{\ct ADIABATIC}                         & Logical         & Section~\ref{info:adiabatic}              &                     & {\ct .FALSE.}           \\ \hline
{\ct AUTO\_IGNITION\_TEMPERATURE}       & Real            & Section~\ref{info:ignition}               & $^\circ$C           & -273                    \\ \hline
{\ct BACKING}                           & Character       & Section~\ref{info:BACKING}                &                     & {\ct 'EXPOSED'}         \\ \hline
{\ct BURN\_AWAY}                        & Logical         & Section~\ref{info:BURN_AWAY}              &                     & {\ct .FALSE.}           \\ \hline
{\ct CELL\_SIZE\_FACTOR}                & Real            & Section~\ref{info:solid_phase_stability}  &                     & 1.0                     \\ \hline
{\ct C\_FORCED\_CONSTANT}               & Real            & Section~\ref{info:convection}             &                     & 0.0                     \\ \hline
{\ct C\_FORCED\_PR\_EXP}                & Real            & Section~\ref{info:convection}             &                     & 0.0                     \\ \hline
{\ct C\_FORCED\_RE}                     & Real            & Section~\ref{info:convection}             &                     & 0.0                     \\ \hline
{\ct C\_FORCED\_RE\_EXP}                & Real            & Section~\ref{info:convection}             &                     & 0.0                     \\ \hline
{\ct C\_HORIZONTAL}                     & Real            & Section~\ref{info:convection}             &                     & 1.52                    \\ \hline
{\ct C\_VERTICAL}                       & Real            & Section~\ref{info:convection}             &                     & 1.31                    \\ \hline
{\ct COLOR    }                         & Character       & Section~\ref{info:colors}                 &                     &                         \\ \hline
{\ct CONVECTION\_LENGTH\_SCALE}         & Real            & Section~\ref{info:convection}             & m                   & 1.                      \\ \hline
{\ct CONVECTIVE\_HEAT\_FLUX}            & Real            & Section~\ref{info:convection}             & \si{kW/m^2}         &                         \\ \hline
{\ct CONVERT\_VOLUME\_TO\_MASS}         & Logical         & Section~\ref{info:MASS_FLUX}              &                     & {\ct .FALSE.}           \\ \hline
{\ct DEFAULT}                           & Logical         & Section~\ref{info:SURF}                   &                     & {\ct .FALSE.}           \\ \hline
{\ct DT\_INSERT}                        & Real            & Section~\ref{info:particle_flux}          & s                   & 0.01                    \\ \hline
{\ct EMISSIVITY}                        & Real            & Section~\ref{info:convection}             &                     & 0.9                     \\ \hline
{\ct EMISSIVITY\_BACK}                  & Real            & Section~\ref{info:BACKING}                &                     &                         \\ \hline
{\ct EVAC\_DEFAULT}                     & Logical         & Reference~\cite{FDS_Evac_Users_Guide}     &                     & {\ct .FALSE.}           \\ \hline
{\ct E\_COEFFICIENT}                    & Real            & Section~\ref{info:suppression}            & \si{m^2/(kg.s)}     &                         \\ \hline
{\ct EXTERNAL\_FLUX}                    & Real            & Section~\ref{solid_phase_verification}    & \si{kW/m^2}         &                         \\ \hline
{\ct EXTINCTION\_TEMPERATURE}           & Real            & Section~\ref{info:specified_burning}      & $^\circ$C           & -273.                   \\ \hline
{\ct FREE\_SLIP}                        & Logical         & Section~\ref{info:WALL_MODEL}             &                     & {\ct .FALSE.}           \\ \hline
{\ct GEOMETRY}                          & Character       & Section~\ref{info:GEOMETRY}               &                     & {\ct 'CARTESIAN'}       \\ \hline
{\ct HEAT\_OF\_VAPORIZATION}            & Real            & Section~\ref{info:specified_burning}      & kJ/kg               &                         \\ \hline
{\ct HEAT\_TRANSFER\_COEFFICIENT}       & Real            & Section~\ref{info:convection}             & \si{W/(m^2.K)}      &                         \\ \hline
{\ct \footnotesize HEAT\_TRANSFER\_COEFFICIENT\_BACK} & Real            & Section~\ref{info:convection}             & \si{W/(m^2.K)}      &                         \\ \hline
{\ct HEAT\_TRANSFER\_MODEL}             & Character       & Section~\ref{info:convection}             &                     &                         \\ \hline
{\ct HRRPUA}                            & Real            & Section~\ref{info:gas_burner}             & \si{kW/m^2}         &                         \\ \hline
{\ct HT3D}                              & Logical         & Section~\ref{info:ht3d}                   &                     & {\ct .FALSE.}           \\ \hline
{\ct ID}                                & Character       & Section~\ref{info:SURF}                   &                     &                         \\ \hline
{\ct IGNITION\_TEMPERATURE}             & Real            & Section~\ref{info:specified_burning}      & $^\circ$C           & 5000.                   \\ \hline
{\ct INNER\_RADIUS}                     & Real            & Section~\ref{info:PART_GEOMETRY}          & m                   &                         \\ \hline
{\ct INTERNAL\_HEAT\_SOURCE}            & Real Array      & Section~\ref{info:INTERNAL_HEAT_SOURCE}   & kW/m$^3$            &                         \\ \hline
{\ct LAYER\_DIVIDE}                     & Real            & Section~\ref{info:EXPOSED}                &                     & {\ct N\_LAYERS}/2       \\ \hline
{\ct LEAK\_PATH}                        & Int.~Pair       & Section~\ref{info:Leaks}                  &                     &                         \\ \hline
{\ct LENGTH}                            & Real            & Section~\ref{info:PART_GEOMETRY}          & m                   &                         \\ \hline
{\ct MASS\_FLUX(:)}                     & Real Array      & Section~\ref{info:MASS_FLUX}              & \si{kg/(m^2.s)}     &                         \\ \hline
{\ct MASS\_FLUX\_TOTAL}                 & Real            & Section~\ref{info:MASS_FLUX_TOTAL}        & \si{kg/(m^2.s)}     &                         \\ \hline
{\ct MASS\_FLUX\_VAR}                   & Real            & Section~\ref{info:MASS_FLUX_VAR}          &                     &                         \\ \hline
{\ct MASS\_FRACTION(:)}                 & Real Array      & Section~\ref{info:MASS_FLUX}              &                     &                         \\ \hline
{\ct MASS\_TRANSFER\_COEFFICIENT}       & Real            & Section~\ref{info:liquid_fuels}           & m/s                 &                         \\ \hline
{\ct MATL\_ID(NL,NC)}                   & Char.~Array     & Section~\ref{info:solid_pyrolysis}        &                     &                         \\ \hline
{\ct MATL\_MASS\_FRACTION(NL,NC)}       & Real Array      & Section~\ref{info:solid_pyrolysis}        &                     &                         \\ \hline
{\ct MINIMUM\_LAYER\_THICKNESS}         & Real            & Section~\ref{info:solid_phase_stability}  & m                   & 1.E-6                   \\ \hline
{\ct MLRPUA }                           & Real            & Section~\ref{info:gas_burner}             & \si{kg/(m^2.s)}     &                         \\ \hline
{\ct N\_LAYER\_CELLS\_MAX}              & Integer Array   & Section~\ref{info:solid_phase_stability}  &                     & 1000                    \\ \hline
{\ct NET\_HEAT\_FLUX}                   & Real            & Section~\ref{info:convection}             & kW/m$^2$            &                         \\ \hline
{\ct NO\_SLIP}                          & Logical         & Section~\ref{info:WALL_MODEL}             &                     & {\ct .FALSE.}           \\ \hline
{\ct NPPC}                              & Integer         & Section~\ref{info:particle_flux}          &                     & 1                       \\ \hline
{\ct PARTICLE\_MASS\_FLUX}              & Real            & Section~\ref{info:particle_flux}          & \si{kg/(m^2.s)}     &                         \\ \hline
{\ct PARTICLE\_SURFACE\_DENSITY}        & Real            & Section~\ref{info:particle_flux}          & kg/m$^2$            &                         \\ \hline
{\ct PART\_ID}                          & Character       & Section~\ref{info:particle_flux}          &                     &                         \\ \hline
{\ct PLE}                               & Real            & Section~\ref{info:stratification}         &                     & 0.3                     \\ \hline
{\ct PROFILE}                           & Character       & Section~\ref{info:profiles}               &                     &                         \\ \hline
{\ct RADIUS}                            & Real            & Section~\ref{info:PART_GEOMETRY}          & m                   &                         \\ \hline
{\ct RAMP\_EF}                          & Character       & Section~\ref{info:RAMP_Time}              &                     &                         \\ \hline
{\ct RAMP\_MF(:)}                       & Character       & Section~\ref{info:RAMP_Time}              &                     &                         \\ \hline
{\ct RAMP\_PART}                        & Character       & Section~\ref{info:RAMP_Time}              &                     &                         \\ \hline
{\ct RAMP\_Q}                           & Character       & Section~\ref{info:RAMP_Time}              &                     &                         \\ \hline
{\ct RAMP\_T}                           & Character       & Section~\ref{info:RAMP_Time}              &                     &                         \\ \hline
{\ct RAMP\_T\_I}                        & Character       & Section~\ref{info:TMP_INNER}              &                     &                         \\ \hline
{\ct RAMP\_V}                           & Character       & Section~\ref{info:RAMP_Time}              &                     &                         \\ \hline
{\ct RAMP\_V\_X}                        & Character       & Section~\ref{info:RAMP_Vel_Prof}          &                     &                         \\ \hline
{\ct RAMP\_V\_Y}                        & Character       & Section~\ref{info:RAMP_Vel_Prof}          &                     &                         \\ \hline
{\ct RAMP\_V\_Z}                        & Character       & Section~\ref{info:RAMP_Vel_Prof}          &                     &                         \\ \hline
{\ct RGB(3)}                            & Int.~Triplet    & Section~\ref{info:colors}                 &                     & \small 255,204,102      \\ \hline
{\ct ROUGHNESS}                         & Real            & Section~\ref{info:WALL_MODEL}             & m                   & 0.                      \\ \hline
{\ct SPEC\_ID}                          & Character       & Section~\ref{info:MASS_FLUX}              &                     &                         \\ \hline
{\ct SPREAD\_RATE}                      & Real            & Section~\ref{info:spread}                 & m/s                 &                         \\ \hline
{\ct STRETCH\_FACTOR(:) }               & Real            & Section~\ref{info:solid_phase_stability}  &                     & 2.                      \\ \hline
{\ct TAU\_EF}                           & Real            & Section~\ref{info:RAMP_Time}              & s                   & 1.                      \\ \hline
{\ct TAU\_MF(:)}                        & Real            & Section~\ref{info:RAMP_Time}              & s                   & 1.                      \\ \hline
{\ct TAU\_PART}                         & Real            & Section~\ref{info:RAMP_Time}              & s                   & 1.                      \\ \hline
{\ct TAU\_Q}                            & Real            & Section~\ref{info:RAMP_Time}              & s                   & 1.                      \\ \hline
{\ct TAU\_T}                            & Real            & Section~\ref{info:RAMP_Time}              & s                   & 1.                      \\ \hline
{\ct TAU\_V}                            & Real            & Section~\ref{info:RAMP_Time}              & s                   & 1.                      \\ \hline
{\ct TEXTURE\_HEIGHT}                   & Real            & Section~\ref{info:texture_map}            & m                   & 1.                      \\ \hline
{\ct TEXTURE\_MAP}                      & Character       & Section~\ref{info:texture_map}            &                     &                         \\ \hline
{\ct TEXTURE\_WIDTH}                    & Real            & Section~\ref{info:texture_map}            & m                   & 1.                      \\ \hline
{\ct TGA\_ANALYSIS}                     & Logical         & Section~\ref{info:TGA_DSC_MCC}            &                     & {\ct .FALSE.}           \\ \hline
{\ct TGA\_FINAL\_TEMPERATURE}           & Real            & Section~\ref{info:TGA_DSC_MCC}            & $^\circ$C           & 800.                    \\ \hline
{\ct TGA\_HEATING\_RATE}                & Real            & Section~\ref{info:TGA_DSC_MCC}            & $^\circ$C/min       & 5.                      \\ \hline
{\ct THICKNESS(NL)}                     & Real Array      & Section~\ref{info:SURF_MATL_Basics}       & m                   &                         \\ \hline
{\ct TMP\_BACK}                         & Real            & Section~\ref{info:TMP_INNER}              & $^\circ$C           & 20.                     \\ \hline
{\ct TMP\_FRONT}                        & Real            & Section~\ref{info:specified_temperature}  & $^\circ$C           & 20.                     \\ \hline
{\ct TMP\_INNER(:)}                     & Real Array      & Section~\ref{info:TMP_INNER}              & $^\circ$C           & 20.                     \\ \hline
{\ct TRANSPARENCY}                      & Real            & Section~\ref{info:colors}                 &                     & 1.                      \\ \hline
{\ct VEL    }                           & Real            & Section~\ref{info:Velocity_BC}            & m/s                 &                         \\ \hline
{\ct VEL\_BULK}                         & Real            & Section~\ref{info:profiles}               & m/s                 &                         \\ \hline
{\ct VEL\_GRAD}                         & Real            & Section~\ref{info:vel_grad}               & 1/s                 &                         \\ \hline
{\ct VEL\_T }                           & Real Pair       & Section~\ref{info:louvers}                & m/s                 &                         \\ \hline
{\ct VOLUME\_FLOW}                      & Real            & Section~\ref{info:Velocity_BC}            & \si{m^3/s}          &                         \\ \hline
{\ct WIDTH}                             & Real            & Section~\ref{info:PART_GEOMETRY}          & m                   &                         \\ \hline
{\ct XYZ(3)}                            & Real Triplet    & Section~\ref{info:spread}                 & m                   &                         \\ \hline
{\ct Z0 }                               & Real            & Section~\ref{info:stratification}         & m                   & 10.                     \\ \hline
\end{longtable}

% Undocumented: FIRELINE_MLR_MAX,N_CELLS_MAX
% VEGETATION, VEGETATION_ARRHENIUS_DEGRAD, VEGETATION_CDRAG, VEGETATION_CHAR_FRACTION,
% VEGETATION_ELEMENT_DENSITY, VEGETATION_GROUND_TEMP, VEGETATION_HEIGHT,
% VEGETATION_INITIAL_TEMP, VEGETATION_LAYERS, VEGETATION_LINEAR_DEGRAD, VEGETATION_LOAD,
% VEGETATION_LSET_IGNITE_TIME, VEGETATION_MOISTURE, VEGETATION_NO_BURN, VEGETATION_SVRATIO,
% VEG_LEVEL_SET_SPREAD, VEG_LSET_ROS_BACK, VEG_LSET_ROS_FLANK, VEG_LSET_ROS_HEAD,
% VEG_LSET_WIND_EXP

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt TABL}}{TABL} (Table Parameters)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Table parameters ({\ct TABL} namelist group)]{For more information see Section~\ref{info:spraypattern}.}
\label{tbl:TABL} \\
\hline
\multicolumn{5}{|c|}{{\ct TABL} (Table Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct TABL} (Table Parameters)} \\
\hline \hline
\endhead
{\ct ID}                & Character   & Section~\ref{info:spraypattern}      &             &     \\ \hline
{\ct TABLE\_DATA(9)}    & Real Array  & Section~\ref{info:spraypattern}      &             &     \\ \hline
\end{longtable}


\vspace{\baselineskip}


\section{\texorpdfstring{{\tt TIME}}{TIME} (Time Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Time parameters ({\ct TIME} namelist group)]{For more information see Section~\ref{info:TIME}.}
\label{tbl:TIME} \\
\hline
\multicolumn{5}{|c|}{{\ct TIME} (Time Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct TIME} (Time Parameters)} \\
\hline \hline
\endhead
{\ct DT}                        & Real       & Section~\ref{info:TIME_Control}           & s           &                 \\ \hline
{\ct EVAC\_DT\_FLOWFIELD}       & Real       & Reference~\cite{FDS_Evac_Users_Guide}     & s           &  0.01           \\ \hline
{\ct EVAC\_DT\_STEADY\_STATE}   & Real       & Reference~\cite{FDS_Evac_Users_Guide}     & s           &  0.05           \\ \hline
{\ct LIMITING\_DT\_RATIO}       & Real       & Section~\ref{info:Errors}                 &               &  0.0001         \\ \hline
{\ct LOCK\_TIME\_STEP}          & Logical    & Section~\ref{info:TIME_Control}           &             & {\ct .FALSE.}   \\ \hline
{\ct RESTRICT\_TIME\_STEP}      & Logical    & Section~\ref{info:TIME_Control}           &             & {\ct .TRUE.}    \\ \hline
{\ct T\_BEGIN}                  & Real       & Section~\ref{info:TIME_Basics}            & s           & 0.              \\ \hline
{\ct T\_END}                    & Real       & Section~\ref{info:TIME_Basics}            & s           & 1.              \\ \hline
{\ct TIME\_SHRINK\_FACTOR}      & Real       & Section~\ref{info:steady_state}           &             & 1.              \\ \hline
{\ct WALL\_INCREMENT}           & Integer    & Section~\ref{info:solid_phase_stability}  &             & 2               \\ \hline
\end{longtable}

\vspace{\baselineskip}

\section{\texorpdfstring{{\tt TRNX, TRNY, TRNZ}}{TRNX, TRNY, TRNZ} (MESH Transformations)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[MESH transformation parameters ({\ct TRN*} namelist groups)]{For more information see Section~\ref{info:TRNX}.}
\label{tbl:TRNX} \\
\hline
\multicolumn{5}{|c|}{{\ct TRNX, TRNY, TRNZ} (MESH Transformations)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct TRNX, TRNY, TRNZ} (MESH Transformations)} \\
\hline \hline
\endhead
{\ct CC    }            & Real          & Section~\ref{info:TRNX}   & m            &     \\ \hline
{\ct IDERIV}            & Integer       & Section~\ref{info:TRNX}   &              &     \\ \hline
{\ct MESH\_NUMBER}      & Integer       & Section~\ref{info:TRNX}   &              &     \\ \hline
{\ct PC    }            & Real          & Section~\ref{info:TRNX}   &              &     \\ \hline
\end{longtable}

\vspace{\baselineskip}



\section{\texorpdfstring{{\tt VENT}}{VENT} (Vent Parameters)}


\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Vent parameters ({\ct VENT} namelist group)]{For more information see Section~\ref{info:VENT}.}
\label{tbl:VENT} \\
\hline
\multicolumn{5}{|c|}{{\ct VENT} (Vent Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct VENT} (Vent Parameters)} \\
\hline \hline
\endhead
{\ct COLOR    }             & Character         & Section~\ref{info:colors}                                 &               &                     \\ \hline
{\ct CTRL\_ID }             & Character         & Section~\ref{info:activate_deactivate}                    &               &                     \\ \hline
{\ct DEVC\_ID }             & Character         & Section~\ref{info:activate_deactivate}                    &               &                     \\ \hline
{\ct DYNAMIC\_PRESSURE}     & Real              & Section~\ref{info:pressure_boundary}                      & Pa            & 0.                  \\ \hline
{\ct EVACUATION    }        & Logical           & Reference~\cite{FDS_Evac_Users_Guide}                     &               &  {\ct .FALSE.}      \\ \hline
{\ct ID }                   & Character         & Section~\ref{info:VENT_Basics}                            &               &                     \\ \hline
{\ct IOR}                   & Integer           & Section~\ref{info:VENT_Trouble}                           &               &                     \\ \hline
{\ct L\_EDDY}               & Real              & Section~\ref{info:synthetic_turbulence}                   & m             & 0.                  \\ \hline
{\ct L\_EDDY\_IJ(3,3)}      & Real Array        & Section~\ref{info:synthetic_turbulence}                   & m             & 0.                  \\ \hline
{\ct MB    }                & Character         & Section~\ref{info:VENT_Basics}                            &               &                     \\ \hline
{\ct MESH\_ID    }          & Character         & Reference~\cite{FDS_Evac_Users_Guide}                     &               &                     \\ \hline
{\ct MULT\_ID    }          & Character         & Section~\ref{info:MULT}                                   &               &                     \\ \hline
{\ct N\_EDDY}               & Integer           & Section~\ref{info:synthetic_turbulence}                   &               & 0                   \\ \hline
{\ct OBST\_ID }             & Character         & Section~\ref{info:activate_deactivate}                    &               &                     \\ \hline
{\ct OUTLINE}               & Logical           & Section~\ref{info:VENT_Basics}                            &               &  {\ct .FALSE.}      \\ \hline
{\ct PBX, PBY, PBZ  }       & Real              & Section~\ref{info:VENT_Basics}                            &               &                     \\ \hline
{\ct PRESSURE\_RAMP}        & Character         & Section~\ref{info:pressure_boundary}                      &               &                     \\ \hline
{\ct REYNOLDS\_STRESS(3,3)} & Real Array        & Section~\ref{info:synthetic_turbulence}                   & m$^2$/s$^2$   & 0.                  \\ \hline
{\ct RGB(3)   }             & Integer Triplet   & Section~\ref{info:colors}                                 &               &                     \\ \hline
{\ct SPREAD\_RATE}          & Real              & Section~\ref{info:spread}                                 & m/s           &  0.05               \\ \hline
{\ct SURF\_ID}              & Character         & Section~\ref{info:VENT_Basics}                            &               &  {\ct 'INERT'}      \\ \hline
{\ct TEXTURE\_ORIGIN(3)}    & Real Triplet      & Section~\ref{info:texture_map}                            & m             & (0.,0.,0.)          \\ \hline
{\ct TMP\_EXTERIOR}         & Real              & Section~\ref{info:Special_VENTS}                          & $^\circ$C     &                     \\ \hline
{\ct TMP\_EXTERIOR\_RAMP}   & Character         & Section~\ref{info:Special_VENTS}                          &               &                     \\ \hline
{\ct TRANSPARENCY}          & Real              & Section~\ref{info:colors}                                 &               &   1.0               \\ \hline
{\ct UVW(3) }               & Real Triplet      & Section~\ref{info:HVAClouvers}                            &               &                     \\ \hline
{\ct VEL\_RMS}              & Real              & Section~\ref{info:synthetic_turbulence}                   & m/s           & 0.                  \\ \hline
{\ct XB(6) }                & Real Sextuplet    & Section~\ref{info:VENT_Basics}                            & m             &                     \\ \hline
{\ct XYZ(3) }               & Real Triplet      & Section~\ref{info:spread}                                 & m             &                     \\ \hline
\end{longtable}


\vspace{\baselineskip}



\section{\texorpdfstring{{\tt WIND}}{WIND} (Wind and Atmospheric Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Wind and atmospheric parameters ({\ct WIND} namelist group)]{For more information see Section~\ref{info:WIND}.}
\label{tbl:WIND} \\
\hline
\multicolumn{5}{|c|}{{\ct WIND} (Wind and atmospheric parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct WIND} (Wind and atmospheric parameters)} \\
\hline \hline
\endhead
%{\ct CORIOLIS\_VECTOR(3)}                       & Real          &                                               &               & 0.                \\ \hline
{\ct DIRECTION}                                 & Real          & Section~\ref{info:WIND}                       & degrees       & 270               \\ \hline
{\ct DT\_MEAN\_FORCING}                         & Real          & Section~\ref{info:WIND}                       & s             & 1.                \\ \hline
{\ct FORCE\_VECTOR(3)}                          & Real          & Section~\ref{info:force_vector}               &               & 0.                \\ \hline
{\ct GROUND\_LEVEL}                             & Real          & Section~\ref{info:stratification}             & m             & 0.                \\ \hline
{\ct L}                                         & Real          & Section~\ref{info:WIND}                       & m             & 0                 \\ \hline
{\ct LAPSE\_RATE}                               & Real          & Section~\ref{info:stratification}             & $^\circ$C/m   & 0                 \\ \hline
{\ct RAMP\_DIRECTION}                           & Character     & Section~\ref{info:WIND}                       &               &                   \\ \hline
{\ct RAMP\_FVX\_T}                              & Character     & Section~\ref{info:force_vector}               &               &                   \\ \hline
{\ct RAMP\_FVY\_T}                              & Character     & Section~\ref{info:force_vector}               &               &                   \\ \hline
{\ct RAMP\_FVZ\_T}                              & Character     & Section~\ref{info:force_vector}               &               &                   \\ \hline
{\ct RAMP\_SPEED}                               & Character     & Section~\ref{info:WIND}                       &               &                   \\ \hline
{\ct RAMP\_TMP0\_Z}                             & Character     & Section~\ref{info:stratification}             &               &                   \\ \hline
{\ct RAMP\_U0\_T}                               & Character     & Section~\ref{info:WIND}                       &               &                   \\ \hline
{\ct RAMP\_V0\_T}                               & Character     & Section~\ref{info:WIND}                       &               &                   \\ \hline
{\ct RAMP\_W0\_T}                               & Character     & Section~\ref{info:WIND}                       &               &                   \\ \hline
{\ct RAMP\_U0\_Z}                               & Character     & Section~\ref{info:WIND}                       &               &                   \\ \hline
{\ct RAMP\_V0\_Z}                               & Character     & Section~\ref{info:WIND}                       &               &                   \\ \hline
{\ct RAMP\_W0\_Z}                               & Character     & Section~\ref{info:WIND}                       &               &                   \\ \hline
{\ct SPONGE\_CELLS}                             & Integer       & Section~\ref{info:SPONGE_CELLS}               &               & 3                 \\ \hline
{\ct SPEED}                                     & Real          & Section~\ref{info:WIND}                       & m/s           & 0.                \\ \hline
{\ct STRATIFICATION}                            & Logical       & Section~\ref{info:stratification}             &               & {\ct .TRUE.}      \\ \hline
{\ct THETA\_STAR}                               & Real          & Section~\ref{info:WIND}                       & K             &                   \\ \hline
{\ct U0,V0,W0}                                  & Reals         & Section~\ref{info:WIND}                       & m/s           & 0.                \\ \hline
{\ct U\_STAR}                                   & Real          & Section~\ref{info:WIND}                       & m/s           &                   \\ \hline
%{\ct USE_ATMOSPHERIC_INTERPOLATION}             & Logical       & Flux match TMP for atmospheric flows          &               & {\ct .FALSE.}      \\ \hline
{\ct Z\_0}                                      & Real          & Section~\ref{info:WIND}                       & m             & 0.03              \\ \hline
{\ct Z\_REF}                                    & Real          & Section~\ref{info:WIND}                       & m             & 2.                \\ \hline
\end{longtable}

\vspace{\baselineskip}


\section{\texorpdfstring{{\tt ZONE}}{ZONE} (Pressure Zone Parameters)}

\begin{longtable}{@{\extracolsep{\fill}}|l|l|l|l|l|}
\caption[Pressure zone parameters ({\ct ZONE} namelist group)]{For more information see Section~\ref{info:ZONE}.}
\label{tbl:ZONE} \\
\hline
\multicolumn{5}{|c|}{{\ct ZONE} (Pressure Zone Parameters)} \\
\hline \hline
\endfirsthead
\caption[]{Continued} \\
\hline
\multicolumn{5}{|c|}{{\ct ZONE} (Pressure Zone Parameters)} \\
\hline \hline
\endhead
{\ct ID}                           & Character             & Section~\ref{info:ZONE_Basics}     &        &               \\ \hline
{\ct LEAK\_AREA(N)}                & Real                  & Section~\ref{info:Leaks}           & m$^2$  & 0             \\ \hline
{\ct LEAK\_PRESSURE\_EXPONENT(N)}  & Real                  & Section~\ref{info:Leaks}           &        & 0.5           \\ \hline
{\ct LEAK\_REFERENCE\_PRESSURE(N)} & Real                  & Section~\ref{info:Leaks}           & Pa     & 4             \\ \hline
{\ct PERIODIC}                     & Logical               & Section~\ref{info:ZONE_Basics}     &        & {\ct .FALSE.} \\ \hline
{\ct XB(6)}                        & Real Sextuplet        & Section~\ref{info:ZONE_Basics}     & m      &               \\ \hline
{\ct XYZ(3:N)}                     & Real Triplet Array    & Section~\ref{info:ZONE_Basics}     & m      &               \\ \hline
\end{longtable}







\part{FDS and Smokeview Development Tools}

\chapter{The FDS and Smokeview Repositories}

For those interested in obtaining the FDS and Smokeview source codes, either for development work or simply to compile on a particular platform, it is strongly suggested that you download onto your computer the FDS and Smokeview repositories. All project documents are maintained using the online utility \href{https://github.com/}{{GitHub}}, a free service that supports software development for open source applications.  GitHub uses Git version control software. Under this system, a centralized repository containing all project files resides on a GitHub server.  Anyone can obtain a copy of the repository or retrieve a specific revision of the repository.  However, only the FDS and Smokeview developers can commit changes directly to the repository. Others must submit a ``pull request.'' Detailed instructions for checking out the FDS repository can be found at
\href{https://github.com/firemodels/fds}{{https://github.com/firemodels/fds}}.

Both FDS and Smokeview live within a GitHub \emph{organization} called ``firemodels''.  The current location of the organization is \href{https://github.com/firemodels}{{https://github.com/firemodels}}.  The repositories that are used by the FDS and Smokeview projects are listed below along with a brief description:

\vskip\baselineskip
\begin{tabular}{ll}
fds & FDS source code, verification and validation tests, wikis, and documentation \\
smv & Smokeview source code, integration tests, and documentation \\
exp & Experimental data repository for FDS validation \\
out & FDS output results for validation \\
bot & Firebot (continuous integration system) source \\
fds-smv & Web page html source
\end{tabular}
\vskip\baselineskip

\noindent The wiki pages in the fds repository are particularly useful in describing the details of how you go about working with the repository assets.





\chapter{Compiling FDS}
\label{info:compilation}

If a compiled version of FDS exists for the machine on which the calculation is to be run and no changes have been made to the original source code, there is no need to re-compile the code. For example, the file {\ct fds.exe} is the compiled program for a Windows-based PC; thus PC users do not need a Fortran compiler and do not need to compile the source code. For machines for which an executable has not been compiled, you must compile the code. A Fortran 2008 compliant compiler is required.

\section{FDS Source Code}

Table~\ref{tab:sourcefiles} lists the files that make up the FDS source code. Files with the ``.f90'' suffix contain free-form Fortran~90 instructions conforming to the ANSI and ISO standards (2008 edition). A {\ct makefile} is available in the Build directory of the fds Repository that contains platform specific options for compilation. Note the following:
\begin{itemize}
\item The source code consists entirely of Fortran statements organized into 33 files. Some compilers have a standard optimization level, plus various degrees of ``aggressive'' optimization. Be cautious in using the highest levels of optimization.
\item To compile FDS, you need a Fortran compiler (2008 or greater) and MPI libraries. More details on MPI can be found at the FDS repository
\href{https://github.com/firemodels/fds}{{https://github.com/firemodels/fds}}.
\end{itemize}

\begin{table}[ht]
\begin{center}
\caption{FDS source code files}
\label{tab:sourcefiles}
\vspace{.1in}
\begin{tabular}{|l|l|}
\hline
File Name  & Description  \\ \hline \hline
{\ct cons.f90}   & Global arrays and constants \\ \hline
{\ct ctrl.f90}   & Definitions and routines for control functions \\ \hline
{\ct data.f90}   & Data for output quantities and thermophysical properties\\ \hline
{\ct devc.f90}   & Derived type definitions and constants for devices \\ \hline
{\ct divg.f90}   & Compute the flow divergence \\ \hline
{\ct dump.f90}   & Output data dumps into files \\ \hline
{\ct evac.f90}   & Egress computations (future capability) \\ \hline
{\ct fire.f90}   & Combustion routines \\ \hline
{\ct func.f90}   & Global functions and subroutines \\ \hline
{\ct geom.f90}   & Routines supporting complex, unstructured geometry (under development) \\ \hline
{\ct gsmv.f90}   & Routines supporting complex, unstructured geometry (under development) \\ \hline
{\ct hvac.f90}   & Heating, Ventilation, and Air Conditioning \\ \hline
{\ct ieva.f90}   & Support routines for evac.f90 \\ \hline
{\ct init.f90}   & Initialize variables and Poisson solver \\ \hline
{\ct irad.f90}   & Functions needed for radiation solver, including RadCal \\ \hline
{\ct main.f90}   & Main program \\ \hline
{\ct mass.f90}   & Mass equation(s) and thermal boundary conditions \\ \hline
{\ct mesh.f90}   & Arrays and constants associated with each mesh \\ \hline
{\ct part.f90}   & Lagrangian particle transport and sprinkler activation \\ \hline
{\ct pois.f90}   & Poisson (pressure) solver \\ \hline
{\ct prec.f90}   & Specification of numerical precision \\ \hline
{\ct pres.f90}   & Spatial discretization of pressure (Poisson) equation \\ \hline
{\ct radi.f90}   & Radiation solver  \\ \hline
{\ct read.f90}   & Read input parameters \\ \hline
{\ct samr.f90}   & Simplified Adaptive Mesh Refinement (under development) \\ \hline
{\ct scrc.f90}   & Alternative pressure solver (under development) \\ \hline
{\ct smvv.f90}   & Routines for computing and outputting 3D smoke and isosurfaces \\ \hline
{\ct soot.f90}   & Soot agglomeration and aerosol deposition \\ \hline
{\ct turb.f90}   & Turbulence models and manufactured solutions \\ \hline
{\ct type.f90}   & Derived type definitions \\ \hline
{\ct vege.f90}   & Experimental vegetation model \\ \hline
{\ct velo.f90}   & Momentum equations \\ \hline
{\ct wall.f90}   & Wall boundary conditions \\ \hline
\end{tabular}
\end{center}
\end{table}





\chapter{Output File Formats}

The output from the code consists of the file {\ct CHID.out}, plus various data files that are described below. Most of these output files are written out by the subroutines within {\ct dump.f90}, and can easily be modified to accommodate various plotting packages.

\section{Diagnostic Output}
\label{out:file}

The file {\ct CHID.out} contains diagnostic output, including an accounting of various important quantities, including CPU usage. Typically, diagnostic information is printed out every 100 time steps as follows:
\begin{lstlisting}
Time Step  137431   December 27, 2015  00:29:49
Step Size:    0.563E-01 s, Total Time:    1800.04 s
Pressure Iterations:      1
Maximum Velocity Error:  0.30E-01 on Mesh   1 at (   0  44   3)
---------------------------------------------------------------
Max CFL number:  0.94E+00 at (  1, 46,  1)
Max divergence:  0.13E+00 at ( 66, 12,  1)
Min divergence: -0.20E+00 at ( 66, 13,  1)
Max VN number:   0.51E+00 at (  1, 25, 18)
No. of Lagrangian Particles:            27
Radiation Loss to Boundaries:        13.830 kW
\end{lstlisting}
The {\ct Time Step} indicates the total number of iterations. The date and time indicate the current wall clock time. The {\ct STEP SIZE} indicates the size of the numerical time step. The {\ct Total Time} indicates the total simulation time calculated up to that point. The {\ct Pressure Iterations} are the number of iterations of the pressure solver for the corrector (second) half of the time step. The pressure solver iterations are designed to minimize the error in the normal component of velocity at solid walls or the interface of two meshes. The {\ct Maximum Velocity Error} indicates this error and in which grid cell it occurs.  {\ct Max/Min divergence} is the max/min value of the function $\nabla \cdot \bu$ and is used as a diagnostic when the flow is incompressible (i.e., no heating); {\ct Max CFL number} is the maximum value of the CFL number, the primary time step constraint; {\ct Max VN number} is the maximum value of the Von Neumann number, the secondary time step constraint. The {\ct No. of Lagrangian Particles} refers to the number of particles in the current mesh. The {\ct Radiation Loss to Boundaries} is the amount of energy that is being radiated to the boundaries. As compartments heat up, the energy lost to the boundaries can grow to be an appreciable fraction of the {\ct Total Heat Release Rate}.

Following the completion of a successful run, a summary of the CPU usage per subroutine is listed in the file called {\ct CHID\_cpu.csv} (Section~\ref{out:CPU}). This is useful in determining where most of the computational effort is being placed.

\section{Heat Release Rate and Related Quantities}

\label{out:hrr}
The heat release rate of the fire, plus other global energy-related quantities, are automatically written into a text file
called {\ct CHID\_hrr.csv}. The format of the file is as follows
\begin{lstlisting}
s    , kW       , kW       , ... , kg/s      , Pa       , Pa        , ...
Time , HRR      , Q_RADI   , ... , BURN_RATE , ZONE_01  , ZONE_02   , ...
T(1) , VAL(1,1) , VAL(2,1) , ... , VAL(8,1)  , VAL(9,1) , VAL(10,1) , ...
T(2) , VAL(1,2) , VAL(2,2) , ... , VAL(8,2)  , VAL(9,2) , VAL(10,1) , ...
            .
            .
 \end{lstlisting}
Details of the integrated energy quantities can be found in Section~\ref{info:HRR}. {\ct BURN\_RATE} is the total mass loss rate of fuel, and {\ct ZONE\_01}, etc., are the background pressures of the various pressure {\ct ZONE}s. Note that the reported {\ct BURN\_RATE} is not adjusted to account for the possibility that each individual material might have a different heat of combustion. It is the actual burning rate of the fuel as predicted by FDS or specified by you. The background pressure is discussed in Section~\ref{info:ZONE}.


\section{Device Output Data}
\label{out:DEVC}

Data associated with particular devices (link temperatures, smoke obscuration, thermocouples, etc.) specified in the input file under the namelist group {\ct DEVC} is output in comma delimited format in a file called {\ct CHID\_devc.csv}. The format of the file is as follows:
\begin{lstlisting}
s    , UNITS(1) , UNITS(2) , ... , UNITS(N_DEVC)
Time , ID(1)    , ID(2)    , ... , ID(N_DEVC)
T(1) , VAL(1,1) , VAL(2,1) , ... , VAL(N_DEVC,1)
T(2) , VAL(1,2) , VAL(2,2) , ... , VAL(N_DEVC,2)
                      .
                      .
\end{lstlisting}
where {\ct N\_DEVC} is the number of devices, {\ct ID(I)} is the user-defined ID of the {\ct I}th device, {\ct UNITS(I)} the units, {\ct T(J)} the time of the {\ct J}th dump, and
{\ct VAL(I,J)} the value at the {\ct I}th device at the {\ct J}th time. The files can be imported into Microsoft Excel or almost any other spreadsheet program. If the number of device columns exceeds {\ct DEVC\_COLUMN\_LIMIT}, the file will automatically be split into smaller files.

\section{Control Output Data}
\label{out:CTRL}

Data associated with particular control functions specified in the input file under the namelist group {\ct CTRL} is output in comma delimited format in a file called {\ct CHID\_ctrl.csv}. The format of the file is as follows:
\begin{lstlisting}
s    , status , status , ... , status
Time , ID(1)  , ID(2)  , ... , ID(N_CTRL)
T(1) , -001   , 001    , ... , -001
            .
            .
\end{lstlisting}
where {\ct N\_CTRL} is the number of controllers, {\ct ID(I)} is the user-defined ID of the {\ct I}th control function, and plus or minus 1's represent the state {\ct -1 = .FALSE. and +1 = .TRUE.} of the {\ct I}th control function at the particular time. The files can be imported into Microsoft Excel or almost any other spreadsheet program. If the number of control columns exceeds {\ct CTRL\_COLUMN\_LIMIT}, the file will automatically be split into smaller files.

\section{CPU Usage Data}
\label{out:CPU}

The file called {\ct CHID\_cpu.csv} records the amount of CPU time for each of the MPI processes.
\begin{lstlisting}
Rank,MAIN,DIVG, ... , Total T_USED (s)
    0, 2.052E+00, 1.058E+01, ... , 5.143+01
    1, 2.432E+00, 1.062E+01, ... , 5.123+01
            .
            .
\end{lstlisting}
where {\ct Rank} is the number of the MPI process (starting at 0), {\ct MAIN}, {\ct DIVG}, and so on, are major routines, and {\ct 'Total T\_USED (s)'} is the total CPU time consumed by that particular MPI process. Typically, the total time is similar. The time spent in {\ct MAIN} is essentially overhead -- time spent {\em not} working on the calculation. If you want to know if your work load is balanced, take a look at the time spent in {\ct MAIN}. It should be similar for all MPI processes. If one of the MPI processes has a noticeably smaller value for {\ct MAIN}, then that process is working on the core routines while the other processes sit idle in {\ct MAIN}.

The {\ct CHID\_cpu.csv} file is printed out at the end of the simulation. To force it to be printed out periodically during the simulation, set {\ct DT\_CPU} on the {\ct DUMP} line. Its default value is very large, meaning that by default, the CPU information is only printed at the end of the simulation.

\section{Gas Mass Data}

The total mass of the various gas species at any instant in time is reported in the comma delimited file {\ct CHID\_mass.csv}. The file consists of several columns, the first column containing the time in seconds, the second contains the total mass of all the gas species in the computational domain in units of kg, the next lines contain the total mass of the individual species.

You must specifically ask that this file be generated, as it can potentially cost a fair amount of CPU time to generate. Set {\ct MASS\_FILE=.TRUE.} on the {\ct DUMP} line to create this output file.


\section{Slice Files}
\label{out:SLCF}

The slice files defined under the namelist group {\ct SLCF} are named {\ct CHID\_$n$.sf} ($n$=01,02...), and are written out unformatted, unless otherwise directed. These files are written out from {\ct dump.f90} with the following lines:
\begin{lstlisting}
WRITE(LUSF) QUANTITY
WRITE(LUSF) SHORT_NAME
WRITE(LUSF) UNITS
WRITE(LUSF) I1,I2,J1,J2,K1,K2
WRITE(LUSF) TIME
WRITE(LUSF) (((QQ(I,J,K),I=I1,I2),J=J1,J2),K=K1,K2)
        .
        .
WRITE(LUSF) TIME
WRITE(LUSF) (((QQ(I,J,K),I=I1,I2),J=J1,J2),K=K1,K2)
\end{lstlisting}
{\ct QUANTITY}, {\ct SHORT\_NAME} and {\ct UNITS} are character strings of length 30. The sextuplet ({\ct I1,I2,J1,J2,K1,K2}) denotes the bounding mesh cell nodes. The sextuplet indices correspond to mesh cell nodes, or corners, thus the entire mesh would be represented by the sextuplet ({\ct 0,IBAR,0,JBAR,0,KBAR}).

There is a short Fortran 90 program provided, called {\ct fds2ascii.f90}, that can convert slice files into text files that can be read into a variety of graphics packages. The program combines multiple slice files corresponding to the same ``slice'' of the computational domain, time-averages the data, and writes the values into one file, consisting of a line of numbers for each node. Each line contains the physical coordinates of the node, and the time-averaged quantities corresponding to that node. In particular, the graphics package Tecplot reads this file and produces contour, streamline and/or vector plots. See Section~\ref{info:fds2ascii} for more details about the program {\ct fds2ascii}.

\section{Plot3D Data}
\label{out:PL3D}

Quantities over the entire mesh can be output in a format used by the graphics package Plot3D. The Plot3D data sets are single precision (32 bit reals), whole and unformatted. Note that there is blanking, that is, blocked out data points are not plotted. If the statement {\ct WRITE\_XYZ=.TRUE.} is included on the {\ct DUMP} line, then the mesh data is written out to a file called {\ct CHID.xyz}
\begin{lstlisting}
WRITE(LU13) IBAR+1,JBAR+1,KBAR+1
WRITE(LU13) (((X(I),I=0,IBAR),J=0,JBAR),K=0,KBAR), &
            (((Y(J),I=0,IBAR),J=0,JBAR),K=0,KBAR), &
            (((Z(K),I=0,IBAR),J=0,JBAR),K=0,KBAR), &
     (((IBLK(I,J,K),I=0,IBAR),J=0,JBAR),K=0,KBAR)
\end{lstlisting}
where {\ct X, Y} and {\ct Z} are the coordinates of the cell corners, and {\ct IBLK} is an indicator of whether or not the cell is blocked. If the point ({\ct X,Y,Z}) is completely embedded within a solid region, then {\ct IBLK} is 0. Otherwise, {\ct IBLK} is 1. Normally, the mesh file is not dumped.

The flow variables are written to a file called {\ct CHID\_****\_**.q}, where the stars indicate a time at which the data is output. The file is written with the lines
\begin{lstlisting}
WRITE(LU14) IBAR+1,JBAR+1,KBAR+1
WRITE(LU14) ZERO,ZERO,ZERO,ZERO
WRITE(LU14) ((((QQ(I,J,K,N),I=0,IBAR),J=0,JBAR),K=0,KBAR),N=1,5)
\end{lstlisting}
The five channels {\ct N=1,5} are by default the temperature ($^\circ$C), the $u$, $v$ and $w$ components of the velocity (m/s), and the heat release rate per unit volume (kW/m$^3$). Alternate variables can be specified with the input parameter {\ct PLOT3D\_QUANTITY(1:5)} on the {\ct DUMP} line. Note that the data is interpolated at cell corners, thus the dimensions of the Plot3D data sets are one larger than the dimensions of the computational mesh.

Smokeview can display the Plot3D data. In addition, the Plot3D data sets can be read into some other graphics programs that accept the data format. This particular format is very convenient, and recognized by a number of graphics packages.


\section{Boundary Files}
\label{out:BNDF}

The boundary files defined under the namelist group {\ct BNDF} are named {\ct CHID\_$n$.bf} ($n$=0001,0002...), and are written out unformatted. These files are written out from {\ct dump.f90} with the following lines:
\begin{lstlisting}
WRITE(LUBF) QUANTITY
WRITE(LUBF) SHORT_NAME
WRITE(LUBF) UNITS
WRITE(LUBF) NPATCH
WRITE(LUBF) I1,I2,J1,J2,K1,K2,IOR,NB,NM
WRITE(LUBF) I1,I2,J1,J2,K1,K2,IOR,NB,NM
        .
        . WRITE(LUBF) TIME
WRITE(LUBF) (((QQ(I,J,K),I=11,I2),J=J1,J2),K=K1,K2)
WRITE(LUBF) (((QQ(I,J,K),I=11,I2),J=J1,J2),K=K1,K2)
        .
        . WRITE(LUBF) TIME
WRITE(LUBF) (((QQ(I,J,K),I=11,I2),J=J1,J2),K=K1,K2)
WRITE(LUBF) (((QQ(I,J,K),I=11,I2),J=J1,J2),K=K1,K2) .
        .
\end{lstlisting}
{\ct QUANTITY}, {\ct SHORT\_NAME} and {\ct UNITS} are character strings of length 30. {\ct NPATCH} is the number of planes (or ``patches'') that make up the solid boundaries plus the external walls. The sextuplet ({\ct I1,I2,J1,J2,K1,K2}) defines the cell nodes of each patch. {\ct IOR} is an integer indicating the orientation of the patch ($\pm 1,\pm 2,\pm 3$). You do not prescribe these. {\ct NB} is the number of the boundary (zero for external walls) and {\ct NM} is the number of the mesh.  Note that the data is planar, thus one pair of cell nodes is the same. Presently, Smokeview is the
only program available to view the boundary files.

\section{Particle Data}
\label{out:PART}

Coordinates and specified quantities related to tracer particles, sprinkler droplets, and other Lagrangian particles are written
to a FORTRAN unformatted (binary) file called {\ct CHID.prt5}.
Note that the format of this file has changed from previous versions (4 and below).
The file consists of some header material, followed by particle data output every
{\ct DT\_PART} seconds. The time increment {\ct DT\_PART} is specified on the
{\ct DUMP} line. It is {\ct T\_END/NFRAMES} by default.
The header materials is written by the following FORTRAN code in the file called {\ct dump.f90}.

\begin{lstlisting}
WRITE(LUPF) ONE_INTEGER          ! Integer 1 to check Endian-ness
WRITE(LUPF) NINT(VERSION*100.)   ! FDS version number
WRITE(LUPF) N_PART               ! Number of PARTicle classes
DO N=1,N_PART
   PC => PARTICLE_CLASS(N)
   WRITE(LUPF) PC%N_QUANTITIES,ZERO_INTEGER  ! ZERO_INTEGER is a place holder
   DO NN=1,PC%N_QUANTITIES
      WRITE(LUPF) CDATA(PC%QUANTITIES_INDEX(NN))  ! 30 character output quantity
      WRITE(LUPF) UDATA(PC%QUANTITIES_INDEX(NN))  ! 30 character output units
   ENDDO
ENDDO
\end{lstlisting}
Note that the initial printout of the number 1 is used by Smokeview to determine the
Endian-ness of the file. The Endian-ness has to do with the particular way real numbers are written into a binary file.
The version number is used to distinguish new versus old file formats.
The parameter {\ct N\_PART} is not the number of particles, but rather the number of
particle classes corresponding to the {\ct PART} namelist groups in the input file.
Every {\ct DT\_PART} seconds the coordinates of the particles and droplets are output as 4 byte reals (by default):

\begin{lstlisting}
WRITE(LUPF) REAL(T,FB)  ! Write out the time T as a 4 byte real
DO N=1,N_PART
   WRITE(LUPF) NPLIM    ! Number of particles in the PART class
   WRITE(LUPF) (XP(I),I=1,NPLIM),(YP(I),I=1,NPLIM),(ZP(I),I=1,NPLIM)
   WRITE(LUPF) (TA(I),I=1,NPLIM)  ! Integer "tag" for each particle
   IF (PC%N_QUANTITIES > 0) WRITE(LUPF) ((QP(I,NN),I=1,NPLIM),NN=1,PC%N_QUANTITIES)
ENDDO
\end{lstlisting}
The particle ``tag'' is used by Smokeview to keep track of individual particles and droplets for the purpose of drawing
streamlines. It is also useful when parsing the file. The quantity data, {\ct QP(I,NN)}, is used by Smokeview to color
the particles and droplets. Note that it is now possible with the new format to color the particles and droplets with
several different quantities.

\subsubsection*{Increased Precision of Particle File}

Note that if {\ct EB\_PART\_FILE=.TRUE.} is set on the {\ct DUMP} line then the {\ct .prt} file will be written with 8 byte reals instead of 4 byte reals.  This may be useful for development of verification cases, but it renders the {\ct .prt} files unreadable by Smokeview.

\section{Profile Files}
\label{out:PROF}

The profile files defined under the namelist group {\ct PROF} are named {\ct CHID\_prof\_$nn$.csv} ($nn$=01,02...), and are written out formatted. These files are written out from {\ct dump.f90} with the following line:
\begin{lstlisting}
WRITE(LU_PROF) T,NWP+1,(X_S(I),I=0,NWP),(Q(I),I=0,NWP)
\end{lstlisting}
After the time {\ct T}, the number of node points is given and then the node coordinates. These are written out at every time step because the wall thickness and the local solid phase mesh may change over time due to the solid phase reactions. Array {\ct Q} contains the values of the output quantity, which may be wall temperature, density or component density.

\section{3-D Smoke Files}
\label{out:SMOKE3D}

3-D smoke files contain alpha values used by Smokeview to draw semi-transparent planes representing smoke and fire. FDS outputs 3-D smoke data at fixed time intervals.  A {\em pseudo-code} representation of the 3-D smoke file is given by:
\begin{lstlisting}
WRITE(LU_SMOKE3D) ONE,VERSION,0,NX-1,0,NY-1,0,NZ-1
                .
                .
WRITE(LU_SMOKE3D_SIZE,*) TIME,NCHARS_IN,NCHARS_OUT
WRITE(LU_SMOKE3D) TIME
WRITE(LU_SMOKE3D) NCHARS_IN,NCHARS_OUT
IF (NCHARS_OUT > 0) WRITE(LU_SMOKE3D)(BUFFER_OUT(I),I=1,NCHARS_OUT)
\end{lstlisting}
The first {\ct ONE}\ is an endian flag.  Smokeview uses this number to determine whether the computer creating the 3-D smoke file and the computer viewing the 3-D smoke file use the same or different byte swap (endian) conventions for storing floating point numbers.  The opacity data is converted from 4 byte floating point numbers to one byte integers then compressed using run-length encoding (RLE). The compressed data is contained in {\ct BUFFER\_OUT}.  Run-length encoding is a compression scheme where repeated ``runs'' of data are replaced with a number (number of repeats), and the value repeated. Four or more consecutive identical characters are represented by $\# n c$ where $\#$ is a special character denoting the beginning of a repeated sequence, $n$ is the number of repeats and $c$ is the character repeated.  $n$ can be up to 254 (255 is used to represent the {\em special}\ character). Characters not repeated four or more times are listed as is. For example, the character string {\tt aaaaaabbbbbcc} is encoded as {\tt \#6a\#5bcc}.



\section{Geometry, Isosurface Files}
\label{out:GEOMETRY}

Both immersed geometric surfaces (generalized obstructions) and FDS generated isosurfaces are stored using a file format described in this section. Iso-surface files are used to store one or more surfaces where the specified {\ct QUANTITY} is a specified value. FDS outputs iso-surface data at fixed time intervals.  These surfaces are defined in terms of vertices and triangles.  A vertex consists of an $(x,y,z)$ coordinate. A triangle consists of 3 connected vertices.  The file format allows one to specify objects that change with time. Static geometry is defined once and displayed by Smokeview unchanged at each time step. Dynamic geometry is defined at each time step either in terms of nodes and faces or in terms of a translation and two rotations (azimuthal and elevation) of dynamic geometry defined in the first time step. These files are written out from {\ct dump.f90} using lines equivalent to the following:
\begin{lstlisting}
! header

WRITE(LU_GEOM) ONE
WRITE(LU_GEOM) VERSION
WRITE(LU_GEOM) N_FLOATS
IF (N_FLOATS>0) WRITE(LU_GEOM) (FLOAT_HEADER(I),I=1,N_FLOATS)
WRITE(LU_GEOM) N_INTS
IF (N_INTS>0) WRITE(LU_GEOM) (INT_HEADER(I),I=1,N_INTS)

! static geometry - geometry specified once and appearing at all time steps

WRITE(LU_GEOM) N_VERT_S, N_FACE_S
IF (N_VERT_S>0)  WRITE(LU_GEOM) (Xvert_S(I),Yvert_S(I),Zvert_S(I),I=1,N_VERT_S)
IF (N_FACE_S>0)  WRITE(LU_GEOM) (FACE1_S(I),FACE2_S(I),FACE3_S(I),I=1,N_FACE_S)
IF (N_FACE_S>0)  WRITE(LU_GEOM) (SURF_S(I),I=1,N_FACE_S)

! dynamic geometry - geometry specified and appearing for each time step

WRITE(LU_GEOM) STIME, GEOM_TYPE
IF (GEOM_TYPE.EQ.0) THEN
  WRITE(LU_GEOM) N_VERT_D, N_FACE_D
  IF (N_VERT_D>0) WRITE(LU_GEOM) (Xvert_D(I),Yvert_D(I),Zvert_D(I),I=1,N_VERT_D)
  IF (N_FACE_D>0) WRITE(LU_GEOM) (FACE1_D(I),FACE2_D(I),FACE3_D(I),I=1,N_FACE_D)
  IF (N_FACE_D>0) WRITE(LU_GEOM) (SURF_D(I),I=1,N_FACE_D)
ELSE IF (GEOM_TYPE.EQ.1) THEN
  ! rotation and translation parameters used to transform geometry from first
  ! dynamic time step
  WRITE(LU_GEOM) Xtran, Ytran, Ztran, Xrot0, Yrot0, Zrot0, rot_az, rot_elev
ENDIF
              .
              .
\end{lstlisting}
\begin{itemize}
\item {\ct ONE}\ has the value 1. Smokeview uses this number to determine whether the computer creating the geometry file and the computer viewing the geometry file use the same or different byte swap (endian) conventions for storing floating point numbers.
\item {\ct VERSION}\ currently has value 0 and indicates the version number of this file format.
\item {\ct N\_FLOATS, N\_INTS} The number of floating point and integer data items stored at the beginning of the file.
\item {\ct FLOAT\_HEADER, INT\_HEADER} Floating point and integer data stored at the beginning of the file.
\item {\ct STIME} is the FDS simulation time.
\item {\ct N\_VERT\_S, N\_FACE\_S, N\_VERT\_D, N\_FACE\_D}\ are the number of static and dynamic vertices and faces.
\item {\ct Xvert\_S, Yvert\_S, Zvert\_S, Xvert\_D, Yvert\_D, Zvert\_D}\ are the static and dynamic vertex coordinates.
\item {\ct FACE1\_S, FACE2\_S, FACE3\_S,FACE1\_D, FACE2\_D, FACE3\_D}\ are the static and dynamic vertex indices for each face (triangle).  The indices are numbered relative to how vertices were written out earlier.
\item {\ct SURF\_S, SURF\_D}\ are the static and dynamic SURF indices for each face (triangle).
\item {\ct GEOM\_TYPE}\ is flag indicating how dynamic geometry is represented. If {\ct GEOM\_TYPE}\ is 0 then time dependent geometry is written out in terms of nodes and faces using the same format as the static geometry. If {\ct GEOM\_TYPE}\ is 1 then time dependent geometry is written out in terms of a translation and two rotations.  These transformations are applied to the dynamic geometry defined at the first time step.
\item {\ct Xtran, Ytran, Ztran}\ is the translation applied to the initial dynamic geometry (If {\ct GEOM\_TYPE}\ is 1)
\item {\ct Xrot0, Yrot0, Zrot0}\ is the origin about which rotations occur.
\item {\ct rot\_az, rot\_elev}\ are the azimuthal and elevation rotation angles (in degrees) applied to the initial dynamic geometry.
\end{itemize}

\section{Geometry Data Files}
\label{out:GEOMETRY_DATA}

The geometry data file contains a description of data values computed by FDS on an immersed
geometrical objects.  This file is analogous to the boundary file.
The data written out to a geometry data file MUST correspond to the geometry written out
in the corresponding geometry file.
Geometry data files are written out from {\ct dump.f90} with the lines equivalent to the following:
\begin{lstlisting}[basicstyle=\scriptsize\ttfamily]
  WRITE(LU_GEOM_DATA) ONE
  WRITE(LU_GEOM_DATA) VERSION
  WRITE(LU_GEOM_DATA) STIME
  WRITE(LU_GEOM_DATA) N_VERT_S_VALS,N_VERT_D_VALS,N_FACE_S_VALS,N_FACE_D_VALS
  IF (N_VERT_S_VALS>0)  WRITE(LU_GEOM_DATA) (ValVertStatic(I), I=1,N_VERT_S_VALS)
  IF (N_VERT_D_VALS>0)  WRITE(LU_GEOM_DATA) (ValVertDynamic(I),I=1,N_VERT_D_VALS)
  IF (N_FACE_S_VALS>0)  WRITE(LU_GEOM_DATA) (ValFaceStatic(I), I=1,N_FACE_S_VALS)
  IF (N_FACE_D_VALS>0)  WRITE(LU_GEOM_DATA) (ValFaceDynamic(I),I=1,N_FACE_D_VALS)
              .
              .
\end{lstlisting}
The data values written out in this file correspond to the geometry written out in the geometry file.
\begin{itemize}
\item {\ct ONE}\ has the value 1. Smokeview uses this number to determine whether the computer creating the geometry file and the computer viewing the geometry file use the same or different byte swap (endian) conventions for storing floating point numbers.
\item {\ct VERSION}\ currently has value 0 and indicates the version number of this file format.
\item {\ct STIME} is the FDS simulation time.
\item {\ct N\_VERT\_S\_VALS, N\_FACE\_S\_VALS}\ is the number of data values written out for static vertices and faces.  One can write out data values located at nodes, located at the center of faces or both.
\item {\ct N\_VERT\_D\_VALS, N\_FACE\_D\_VALS}\ is the number of dynamic values written out for dynamic vertices and faces.  One can write out data values located at nodes, located at the center of faces, both or neither (if there is no dynamic geometry).
\item {\ct ValVertStatic, ValFaceStatic}\ static vertex and face data.
\item {\ct ValVertDynamic, ValFaceDynamic}\ dynamic vertex and face data.
\end{itemize}



\backmatter
\nopart %To Fix TOC in PDF output.

\bibliography{../Bibliography/FDS_refs,../Bibliography/FDS_general,../Bibliography/FDS_mathcomp}

\end{document}
